Hugo's Markdown Extensions

Playground
, ,

Introduction

This article focuses on markdown as supported by Hugo and Pandoc. Here are a few good Markdown references and tutorials:

Hugo’s Markdown

Hugo uses the GoldMark as it’s default Markdown processor. Goldmark supports the CommonMark standard, along with:

Hugo Goldmark also supports:

Pandoc’s Markdown

See Pandoc’s Markdown for details.

Markdown Formats

There are many variants of Markdown formats, and each processor may support a range of extensions, and interpret the Markdown specifications in somewhat different ways. The main formats include:

  • CommonMark is a standardization effort intended to create a robust specification. However many commonly used extensions (eg. tables, emoji, attribute lists, ) are not yet covered.
  • GitHub Flavored Markdown - a small set of extensions CommonMark, and very heavily used
  • Pandoc - extensive set of extensions, but strays from the original markdown syntax and extensions somewhat
  • Markdown - this is the classic original version, now obsoleted by CommonMark
  • Multimarkdown - the original extension to Markdown
  • Kramdown - extensive set of extensions based on PHP markdown Extra package and Maruku

Markdown Processors

There are many flavours of Markdown, each with its own characteristics. My requirements included the ability to support tables, and the ability to generate PDF files as well as html.

Major Markdown processors, and the variants of Markdown they support include:

Example of Various Extensions

Inline Extensions

Strikethrough support

  • Strikethrough (~~Strikethrough~~) Github Flavored Markdown
  • Strikethrough (<del>Strikethrough</del>) HTML5 version

Auto-Linking

Superscripts and Subscripts

Are not supported directly. Use \(\LaTeX\)/MathJax/AsciiMath. For example, using \(\LaTeX\) delimiters:

```
\\(r_t \\) \\(x^t\\) \\(y_t^2\\)
```

renders as \(r_t \) \(x^t\) \(y_t^2\)

In order for AsciiMath to be rendered, the MathJax configuration needs to set to one that supports AsciiMath. For example mathjaxConfig: TeX-MML-AM_CHTML

```
\` r_t \`  \` x^t \` \` y_t^2 \`
```

renders as ` r_t ` ` x^t ` ` y_t^2 `

Emoji

Use the site configuration enableEmoji = true to enable emoji. Look on the web for emoji definitions, for example Emojipedia Emoji Cheatsheet. Here are a few examples:

SymbolEmoji
:smile:😄
:cry:😢
:mask:😷
:poop:💩
:thumbsup:👍
:smiley_cat:😺

Footnotes

Footnotes work mostly like reference-style links. A footnote is made of two things: a marker in the text that will become a superscript number; a footnote definition that will be placed in a list of footnotes at the end of the document. A footnote looks like this:

That's some text with a footnote.[^1]
[^1]: And that's the footnote.

That’s some text with a footnote.1

  • Footnote definitions can be found anywhere in the document, but footnotes will always be listed in the order they are linked to in the text.

  • You cannot make two links to the same footnote.

  • Each footnote must have a distinct name. That name will be used to link footnote references to footnote definitions, but has no effect on the numbering of the footnotes. Names can contain any character valid within an id attribute in HTML.

  • Footnotes can contain block-level elements, which means that you can put multiple paragraphs, lists, blockquotes and so on in a footnote. If you want things to align better, you can leave the first line of the footnote empty and put your first paragraph just below:

      Here's text that needs another footnote.[^2]
  [^2]:
      And that's another footnote.

      That's the second paragraph.

Here’s text that needs another footnote.2

Definition Lists

Definition lists are made of terms and definitions of these terms, much like in a dictionary.

A simple definition list is made of a single-line term followed by a colon and the definition for that term. Terms must be separated from the previous definition by a blank line. Definitions can span on multiple lines, in which case they should be indented. But you don’t really have to: if you want to be lazy, you could forget to indent a definition that span on multiple lines and it will still work.

Term 1
:   Definition 1

Term 2 with *inline markup*

:   Definition 2

        { some code, part of Definition 2 }

    Third paragraph of definition 2.
Term 1
Definition 1
Term 2 with inline markup

Definition 2

{ some code, part of Definition 2 }

Third paragraph of definition 2.

Here is another example

Sailboat
:    A hole in the water into which one pours money
:    A challenging, relaxing, enjoyable world of possibilities

Car
:    A pollutor that just loses its value

:    Can get you where you want to go
Sailboat
A hole in the water into which one pours money
A challenging, relaxing, enjoyable world of possibilities
Car
A pollutor that just loses its value

Can get you where you want to go

You can also associate more than one term to a definition:

Term 1
Term 2
:   Definition a

Term 3
:   Definition b
Term 1
Term 2
Definition a
Term 3
Definition b

Tables

The Github-Flavored Markdown table format is supported. Pandoc calls these “pipe_tables”:

|     Name     |       Phone       |
|--------------|-------------------|
| Bill Bourne  | +1 (613) 000-1234 |
| Sarah Bourne | +1 (123) 456-7890 |
NamePhone
Bill Bourne+1 (613) 000-1234
Sarah Bourne+1 (123) 456-7890

A : character can be used in the delimiter row to indicate left, right, or centered justification, as the following example shows:

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |
RightLeftDefaultCenter
12121212
123123123123
1111

Note that captions or other labels are not supported.

Unicode Characters

Since browsers, html, and most tools are now UTF-8 compliant, using UTF-8 characters “just works”. Use a Unicode Character Table to search for your desired character and paste it into your markdown file. Some examples:

UnicodeUTF-8ResultName of Character
U+2318E2 8C 98⌘PLACE OF INTEREST SIGN
U+2325E2 8C A5⌥OPTION KEY
U+21E7E2 87 A7⇧UPWARDS WHITE ARROW (Shift)
U+21EAE2 87 AA⇪UPWARDS WHITE ARROW FROM BAR (Caps Lock)
U+2303E2 8C 83⌃UP ARROWHEAD (Ctrl)
U+232BE2 8C AB⌫ERASE TO THE LEFT (Delete)
U+F8FFEF A3 BFApple Symbol
U+21A9E2 86 A9↩LEFTWARDS ARROW WITH HOOK (Return)
U+00AEC2 AE®REGISTERED SIGN
U+00A9C2 A9©COPYRIGHT SIGN
U+2122E2 84 A2™TRADE MARK SIGN
U+2103E2 84 83℃DEGREE CELSIUS
U+2109E2 84 89℉DEGREE FAHRENHEIT

Using \(\LaTeX\) Expressions

To use \(\LaTeX\) and MathJax features, MathJax must be enabled. For details see the Using ASCIIMath and MathJax page.

\(\LaTeX\) expressions can be placed between MathJax delimiters \\( ... \\). This allows us to print \\(\LaTeX\) symbols.

A detailed list of \(\LaTeX\) symbols can be found at:

Math using MathJax

Refer to Using ASCIIMath and MathJax page for details on using MathJax and AsciiMath in Hugo markdown. Here are two examples:

$$R_{ab} - {\textstyle 1 \over 2}R\,g_{ab} + \Lambda\ g_{ab} = \kappa\, T_{ab}$$

renders as:

$$R_{ab} - {\textstyle 1 \over 2}R,g_{ab} + \Lambda\ g_{ab} = \kappa, T_{ab}$$

$$\forall x, y : \mathbb{Z}, x > 3 \land y < 2 \Rightarrow x^2 - 2y > 5$$

renders as:

$$\forall x, y : \mathbb{Z}, x > 3 \land y < 2 \Rightarrow x^2 - 2y > 5$$

  1. And that’s the footnote. ↩︎

  2. And that’s another footnote.

    That’s the second paragraph. ↩︎