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.
- A word on building speeds
- Adding a table of contents
- Adding notes
- Adding large text
- Adding large images
- Adding image captions
- Adding large quotes
- Adding faded text
- Adding tables
- Adding code blocks
- Adding math
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:
{:.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:
{:.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">.
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
