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. 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:

Full-width image

Markdown:

![Full-width image](https://via.placeholder.com/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:

Full-width image

An optional caption for an image.

Markdown:

![Full-width image](https://via.placeholder.com/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 alignedLeft alignedCenter alignedRight aligned
First body partSecond cellThird cellfourth 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 alignedLeft alignedCenter alignedRight alignedDefault alignedLeft alignedCenter alignedRight alignedDefault alignedLeft alignedCenter alignedRight alignedDefault alignedLeft alignedCenter alignedRight aligned
First body partSecond cellThird cellfourth cellFirst body partSecond cellThird cellfourth cellFirst body partSecond cellThird cellfourth cellFirst body partSecond cellThird cellfourth cell
Second linefoostrongbazSecond linefoostrongbazSecond linefoostrongbazSecond linefoostrongbaz
Third linequuxbazbarThird linequuxbazbarThird linequuxbazbarThird linequuxbazbar
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 alignedLeft alignedCenter alignedRight alignedDefault alignedLeft alignedCenter alignedRight alignedDefault alignedLeft alignedCenter alignedRight alignedDefault alignedLeft alignedCenter alignedRight aligned
First body partSecond cellThird cellfourth cellFirst body partSecond cellThird cellfourth cellFirst body partSecond cellThird cellfourth cellFirst body partSecond cellThird cellfourth cell
Second linefoostrongbazSecond linefoostrongbazSecond linefoostrongbazSecond linefoostrongbaz
Third linequuxbazbarThird linequuxbazbarThird linequuxbazbarThird linequuxbazbar
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">.

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 alignedLeft alignedCenter alignedRight aligned
First body partSecond cellThird cellfourth 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)=x2f(x) = x^2.

Markdown:

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

Block

Example: ϕ(x,y)=ϕ(∑i=1nxiei,∑j=1nyjej)=∑i=1n∑j=1nxiyjϕ(ei,ej)=(x1,…,xn)(ϕ(e1,e1)⋯ϕ(e1,en)⋮⋱⋮ϕ(en,e1)⋯ϕ(en,en))(y1⋮yn)\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

© 2021. All rights reserved.