Skip to content
This repository has been archived by the owner on Aug 8, 2020. It is now read-only.

Latest commit

 

History

History
313 lines (247 loc) · 19 KB

writing.md

File metadata and controls

313 lines (247 loc) · 19 KB
layout title redirect_from
page
Writing
/docs/latest/writing/
/docs/writing/

Hydejack offers a few additional features to markup your markdown. Don't worry, these are merely CSS classes added via the standard {:.my-class} syntax, so that your posts remain compatible with other Jekyll themes.

NOTE: For an introduction to markdown in general, see Mastering Markdown and kramdown Syntax. {:.message}

Table of Contents

  • this unordered seed list will be replaced by toc as unordered list {:toc}

Adding a table of contents

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

Example: see above

Markdown:

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

Adding message boxes

You can add a message box by adding the message class to a paragraph.

Example:

NOTE: You can add a message box. {:.message}

Markdown:

**NOTE**: You can add a message box.
{:.message}

Adding large text

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

Example:

You can add large text. {:.lead}

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{:.lead}

Markdown:

![Full-width image](https://placehold.it/800x100){:.lead}

Adding large quotes

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

Example:

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

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 --- or you don't want viewers to read at all, like when you pull a line form a dirty rap song..

Example:

I'm faded, 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.

However, as you'll discover, this only works for small tables like the one below. Larger (data-) tables will be cut off on the right. Typically, even smaller tables will be cut off when viewed on a mobile device.

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

When it comes to displaying large tables on mobile, there is no one-size-fits-all solution. There are however two straight-forward, CSS-only solutions that are included in Hydejack.

Scroll Table

Adding either scroll-table or scroll-table-small to the CSS classes of a table will enable horizontal scrolling. The -small version will only enable scrolling on "small" screens (< 1080px wide). This is useful when the table displays correctly on desktop, but not mobile.

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
-----------------+------------+-----------------+---------------- -----------------+------------+-----------------+---------------- -----------------+------------+-----------------+---------------- -----------------+------------+-----------------+----------------
Second body Second body Second body Second body
2 line 2 line 2 line 2 line
=================+============+=================+================ =================+============+=================+================ =================+============+=================+================ =================+============+=================+================
Footer row Footer row Footer row Footer row
{:.scroll-table}

Markdown:

| 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      |            |                 |                |
{:.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. Again, the -small version will only enable scrolling on "small" screens (< 1080px wide).

NOTE: This approach only works on simple tables that have a single tbody and an optional thead. {:.message}

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
{:.flip-table}

Markdown:

| 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            |
{:.flip-table}

Two things to keep in mind when using scroll-table, flip-table, scroll-table-small, or flip-table-small:

  • Smaller tables will no longer be stretched to span the full width.
  • The layout engine will not attempt to add line-breaks within cells, making columns that contain text unusually large.

NOTE: When using tables in HTML format (i.e. something that looks like <table>...</table>), add the CSS class by setting the class attribute on table, e.g. <table class="scroll-table">...</table>. {:.message}

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

Example:

// 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

Markdown:

~~~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
~~~

NOTE: I advice against using Jekyll's { % highlight % } ... { % endhighlight % } syntax, especially when using it together with the linenos option, as the generated output will break the page during minification (i.e. during a production build). You can read more about it here and here. {:.message}

Adding math

Hydejack supports math blocks via KaTeX.

Why KaTeX instead of MathJax? KaTeX is faster and more lightweight at the cost of having less features, which, for the purpose of writing blog posts, should be a favorable tradeoff.

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

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} $$

Markdown:

$$
\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}
$$

Continue with Scripts{:.heading data-flip="title"} {:.read-more}