Writing

Hydejack offers a few additional features to markup your content. Don’t worry, these are merely CSS classes added with kramdown’s {:...} syntax, so that your content remains compatible with other Jekyll themes.

1. A word on building speeds
2. Adding a table of contents
3. Adding notes
4. Adding large text
5. Adding large images
6. Adding image captions
7. Adding large quotes
8. Adding faded text
9. Adding tables
   1. Scroll table
   2. Flip table
   3. Small tables
10. Adding code blocks
11. Adding math
    1. Inline
    2. Block

For an introduction to markdown in general, see Mastering Markdown and kramdown Syntax.

A word on building speeds

If building speeds are a problem, try using the --incremental flag, e.g.

bundle exec jekyll serve --incremental

From the Jekyll docs (emphasis mine):

Enable the experimental incremental build feature. Incremental build only re-builds posts and pages that have changed, resulting in significant performance improvements for large sites, but may also break site generation in certain cases.

The breakage occurs when you create new files or change filenames. Also, changing the title, category, tags, etc. of a page or post will not be reflected in pages other then the page or post itself. This makes it ideal for writing new posts and previewing changes, but not setting up new content.

Adding a table of contents

You can add a generated table of contents to any page by adding {:toc} below a list.

Markdown:

* this unordered seed list will be replaced by the toc
{:toc}

You can also create your table of contents as an ordered list (note the 1. instead of *):

1. this ordered seed list will be replaced by the toc
{:toc}

The width of the display has to be larger than 1665px for the ToC to become sticky. Otherwise, the ToC will appear where the seed list is placed in the document. To show the table of contents only on large displays (> 1665px) use the following:

* this unordered seed list will be replaced by the toc 
{:toc .large-only}

A sticky table of contents will reduce the amount of space freed up by the no_break_layout: false setting.
This is necessary to ensure large code blocks or tables don’t overlap with the ToC.

Adding notes

You can add a note by adding the note class to a paragraph.

Example:

You can add a note.

Markdown:

You can add a note.
{:.note}

Edit the note key in _data/strings.yml to change the wording of the default label. To add a note with a specific label, add a title attribute:

A custom label.
{:.note title="Attention"}

A custom label.

Adding large text

You can add large text by adding the lead class to the paragraph.

Example:

You can add large text.

Markdown:

You can add large text.
{:.lead}

Adding large images

You can make an image span the full width by adding the lead class.

Example:

Markdown:

![Full-width image](https://placehold.it/800x100){:.lead width="800" height="100" loading="lazy"}

It is recommended to provide the dimension of the image via the width and height attributes, so that browsers can calculate the layout before the images are loaded. Combining this with the loading="lazy" attribute allows modern browsers to load the images just-in-time as the users scrolls.

Previous versions of Hydejack shipped with a custom JavaScript-based lazy loading solution, but it has been removed in v9 in favor of this more standards-based approach.

Adding image captions

You can add captions to large images by adding the figcaption class to the paragraph after the image:

An optional caption for an image.

Markdown:

![Full-width image](https://placehold.it/800x100){:.lead width="800" height="100" loading="lazy"}

A caption for an image.
{:.figcaption}

Adding large quotes

You can make a quote “pop out” by adding the lead class.

Example:

You can make a quote “pop out”.

Markdown:

> You can make a quote "pop out".
{:.lead}

Adding faded text

You can gray out text by adding the faded class. Use this sparingly and for information that is not essential, as it is more difficult to read.

Example:

I’m faded, faded, faded.

Markdown:

I'm faded, faded, faded.
{:.faded}

Adding tables

Adding tables is straightforward and works just as described in the kramdown docs, e.g.

Default aligned	Left aligned	Center aligned	Right aligned
First body part	Second cell	Third cell	fourth cell

Markdown:

| Default aligned |Left aligned| Center aligned  | Right aligned  |
|-----------------|:-----------|:---------------:|---------------:|
| First body part |Second cell | Third cell      | fourth cell    |

However, it gets tricker when adding large tables. In this case, Hydejack will break the layout and grant the table the entire available screen width to the right:

Default aligned	Left aligned	Center aligned	Right aligned	Default aligned	Left aligned	Center aligned	Right aligned	Default aligned	Left aligned	Center aligned	Right aligned	Default aligned	Left aligned	Center aligned	Right aligned
First body part	Second cell	Third cell	fourth cell	First body part	Second cell	Third cell	fourth cell	First body part	Second cell	Third cell	fourth cell	First body part	Second cell	Third cell	fourth cell
Second line	foo	strong	baz	Second line	foo	strong	baz	Second line	foo	strong	baz	Second line	foo	strong	baz
Third line	quux	baz	bar	Third line	quux	baz	bar	Third line	quux	baz	bar	Third line	quux	baz	bar
Second body				Second body				Second body				Second body
2 line				2 line				2 line				2 line
Footer row				Footer row				Footer row				Footer row

Tables adopts to the font size! You can decrease the size of the table by adding the smaller CSS class. Put {:.smaller} below the Markdown table, or add class="smaller" to a HTML table.

Scroll table

If the extra space still isn’t enough, the table will receive a scrollbar. It is browser default behavior to break the lines inside table cells to fit the content on the screen. By adding the scroll-table class on a table, the behavior is changed to never break lines inside cells, e.g:

Default aligned	Left aligned	Center aligned	Right aligned	Default aligned	Left aligned	Center aligned	Right aligned	Default aligned	Left aligned	Center aligned	Right aligned	Default aligned	Left aligned	Center aligned	Right aligned
First body part	Second cell	Third cell	fourth cell	First body part	Second cell	Third cell	fourth cell	First body part	Second cell	Third cell	fourth cell	First body part	Second cell	Third cell	fourth cell
Second line	foo	strong	baz	Second line	foo	strong	baz	Second line	foo	strong	baz	Second line	foo	strong	baz
Third line	quux	baz	bar	Third line	quux	baz	bar	Third line	quux	baz	bar	Third line	quux	baz	bar
Second body				Second body				Second body				Second body
2 line				2 line				2 line				2 line
Footer row				Footer row				Footer row				Footer row

You can add the scroll-table class to a markdown table by putting {:.scroll-table} in line directly below the table. To add the class to a HTML table, add the it to the class attribute of the table tag, e.g. <table class="scroll-table">.

Flip table

Alternatively, you can “flip” (transpose) the table. Unlike the other approach, this will keep the table head (now the first column) fixed in place.

You can enable this behavior by adding flip-table or flip-table-small to the CSS classes of the table. The -small version will only enable scrolling on “small” screens (< 1080px wide).

This approach only works on simple tables that have a single tbody and an optional thead.

Example:

Default aligned	Left aligned	Center aligned	Right aligned	Default aligned	Left aligned	Center aligned	Right aligned	Default aligned	Left aligned	Center aligned	Right aligned	Default aligned	Left aligned	Center aligned	Right aligned
First body part	Second cell	Third cell	fourth cell	First body part	Second cell	Third cell	fourth cell	First body part	Second cell	Third cell	fourth cell	First body part	Second cell	Third cell	fourth cell
Second line	foo	strong	baz	Second line	foo	strong	baz	Second line	foo	strong	baz	Second line	foo	strong	baz
Third line	quux	baz	bar	Third line	quux	baz	bar	Third line	quux	baz	bar	Third line	quux	baz	bar
4th line	quux	baz	bar	4th line	quux	baz	bar	4th line	quux	baz	bar	4th line	quux	baz	bar
5th line	quux	baz	bar	5th line	quux	baz	bar	5th line	quux	baz	bar	5th line	quux	baz	bar
6th line	quux	baz	bar	6th line	quux	baz	bar	6th line	quux	baz	bar	6th line	quux	baz	bar
7th line	quux	baz	bar	7th line	quux	baz	bar	7th line	quux	baz	bar	7th line	quux	baz	bar
8th line	quux	baz	bar	8th line	quux	baz	bar	8th line	quux	baz	bar	8th line	quux	baz	bar
9th line	quux	baz	bar	9th line	quux	baz	bar	9th line	quux	baz	bar	9th line	quux	baz	bar
10th line	quux	baz	bar	10th line	quux	baz	bar	10th line	quux	baz	bar	10th line	quux	baz	bar
11th line	quux	baz	bar	11th line	quux	baz	bar	11th line	quux	baz	bar	11th line	quux	baz	bar
12th line	quux	baz	bar	12th line	quux	baz	bar	12th line	quux	baz	bar	12th line	quux	baz	bar

You can add the flip-table class to a markdown table by putting {:.flip-table} in line directly below the table. To add the class to a HTML table, add the it to the class attribute of the table tag, e.g. <table class="flip-table">.

Small tables

If a table is small enough to fit the screen even on small screens, you can add the stretch-table class to force a table to use the entire available content width. Note that stretched tables can no longer be scrolled.

Default aligned	Left aligned	Center aligned	Right aligned
First body part	Second cell	Third cell	fourth cell

An optional caption for a table

You can add the stretch-table class to a markdown table by putting {:.stretch-table} in line directly below the table. To add the class to a HTML table, add the it to the class attribute of the table tag, e.g. <table class="stretch-table">.

Just like images, you can add captions to tables by adding the figcaption class to the paragraph after the table.

An optional caption for a table
{:.figcaption}

Adding code blocks

To add a code block without syntax highlighting, simply indent 4 spaces (regular markdown). For code blocks with code highlighting, use ~~~<language>. This syntax is also supported by GitHub. For more information and a list of supported languages, see Rouge.

You can give each code block a filename, by making the first line in the block a comment of the form File: "dir/filename.ext". Use either single quotes ', double quotes ", or backticks ` to surround the filename.

Example:

// file: "code-block.js"
// Example can be run directly in your JavaScript console

// Create a function that takes two arguments and returns the sum of those
// arguments
var adder = new Function("a", "b", "return a + b");

// Call the function
adder(2, 6);
// > 8

An optional caption for a code block

Markdown:

~~~js
// file: "code-block.js"
// Example can be run directly in your JavaScript console

// Create a function that takes two arguments and returns the sum of those
// arguments
var adder = new Function("a", "b", "return a + b");

// Call the function
adder(2, 6);
// > 8
~~~

An optional caption for a code block
{:.figcaption}

DO NOT use Jekyll’s { % highlight % } ... { % endhighlight % } syntax, especially together with the linenos option. The generated table to render the line numbers does not have a CSS class or any other way of differentiating it from regular tables, so that the styles above apply, resulting in a broken page. What’s more, the output from highlight tags isn’t even valid HTML, nesting pre tags inside pre tags, which will in break the site during minification. You can read more about it here and here.

Adding math

Before adding math blocks, make sure you’ve set up math support.

Inline

Example:

Lorem ipsum \(f(x) = x^2\).

Markdown:

Lorem ipsum $$ f(x) = x^2 $$.

Block

Example: \[\begin{aligned} \phi(x,y) &= \phi \left(\sum_{i=1}^n x_ie_i, \sum_{j=1}^n y_je_j \right) \\[2em] &= \sum_{i=1}^n \sum_{j=1}^n x_i y_j \phi(e_i, e_j) \\[2em] &= (x_1, \ldots, x_n) \left(\begin{array}{ccc} \phi(e_1, e_1) & \cdots & \phi(e_1, e_n) \\ \vdots & \ddots & \vdots \\ \phi(e_n, e_1) & \cdots & \phi(e_n, e_n) \end{array}\right) \left(\begin{array}{c} y_1 \\ \vdots \\ y_n \end{array}\right) \end{aligned}\]

An optional caption for a math block

Markdown:

$$
\begin{aligned} %!!15
  \phi(x,y) &= \phi \left(\sum_{i=1}^n x_ie_i, \sum_{j=1}^n y_je_j \right) \\[2em]
            &= \sum_{i=1}^n \sum_{j=1}^n x_i y_j \phi(e_i, e_j)            \\[2em]
            &= (x_1, \ldots, x_n)
               \left(\begin{array}{ccc}
                 \phi(e_1, e_1)  & \cdots & \phi(e_1, e_n) \\
                 \vdots          & \ddots & \vdots         \\
                 \phi(e_n, e_1)  & \cdots & \phi(e_n, e_n)
               \end{array}\right)
               \left(\begin{array}{c}
                 y_1    \\
                 \vdots \\
                 y_n
               \end{array}\right)
\end{aligned}
$$

An optional caption for a math block
{:.figcaption}

KaTeX does not support the align and align* environments. Instead, aligned should be used, e.g. \begin{aligned} ... \end{aligned}.

Continue with Scripts