Markdown

Hugo renders Markdown with Goldmark, a fast, well-maintained parser that conforms to the CommonMark specification and is compatible with GitHub Flavored Markdown (GFM). Everything on this page renders here; constructs flagged as uncommon may not survive in other Markdown applications.

Basic formatting#

Emphasis#

Add emphasis by making text **bold**, _italic_ or ***both***.

Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks for mid-word emphasis — *unfrigging***believable**, A*cat*meow — so the emphasis renders correctly everywhere.

This site also enables Goldmark’s extras extension for ~~strikethrough~~, ++inserted text++, ==highlighted text== and superscript (1^st^). Subscript is not enabled; use the HTML tag instead, as in H<sub>2</sub>O.

Highlight, subscript and superscript are uncommon elsewhere — test them in the target application before relying on them, and note that some applications treat a single tilde pair (~x~) as strikethrough rather than subscript. The HTML tags <mark>, <sub> and <sup> are the portable fallback.

Code#

Denote a word or phrase as code by wrapping it in backticks. If it includes one or more backticks itself, escape it by enclosing the word or phrase in double backticks:

To create a code block, indent every line of the block by at least four spaces or one tab — or better, use a fenced code block: no indentation needed, and a language identifier turns on syntax highlighting.

Horizontal rules#

Use three or more asterisks (***), dashes (---), or underscores (___) on a line by themselves, with a blank line before and after. Without the blank line, the --- turns the text above it into a heading instead.

Typographer replacements#

The typographer extension, enabled by default, replaces certain character combinations with HTML entities:

Headings#

To create a heading, add number signs (#) in front of a word or phrase. The number of number signs corresponds to the heading level: three number signs produce a heading level three (<h3>).

Alternate syntax#

On the line below the text, add any number of == characters for heading level 1 or -- characters for heading level 2:

Heading level 1
===============

Heading level 2
---------------

Heading best practices#

Markdown applications don’t agree on how to handle a missing space between the number signs and the heading name. For compatibility, always put a space between them, and put blank lines before and after a heading.

Heading IDs#

Many Markdown processors support custom IDs for headings — some add them automatically. A custom ID lets you link directly to a heading and target it with CSS. To add one, enclose the custom ID in curly braces on the same line as the heading:

### My Great Heading {#custom-id}

The HTML looks like this:

<h3 id="custom-id">My Great Heading</h3>

Link to a heading with a custom ID by creating a standard link with a number sign (#) followed by the custom heading ID — commonly called an anchor link:

[My Great Heading](#custom-id)

Other websites can link to the heading by adding the custom heading ID to the full URL of the webpage, for example [Heading IDs](https://www.markdownguide.org/extended-syntax#heading-ids).

Links#

To create a link, enclose the link text in brackets and follow it immediately with the URL in parentheses:

My favorite search engine is [Duck Duck Go](https://duckduckgo.com).

Titles#

Optionally add a title for a link, which appears as a tooltip when the user hovers over it. Enclose it in quotation marks after the URL:

[Duck Duck Go](https://duckduckgo.com "The best search engine for privacy")

URLs and email addresses#

To quickly turn a URL or email address into a link, enclose it in angle brackets:

<https://www.markdownguide.org>
<fake@example.com>

Many Markdown processors also turn bare URLs into links automatically, even without brackets. To keep a URL from being linked, denote it as code with backticks: `http://www.example.com`.

Formatting links#

To emphasize a link, add asterisks before and after the brackets and parentheses. To denote a link as code, add backticks inside the brackets:

I love supporting the **[EFF](https://eff.org)**.
This is the _[Markdown Guide](https://www.markdownguide.org)_.
See the section on [`code`](#code).

Reference-style links#

Reference-style links keep long URLs out of the paragraph, which makes the raw text easier to read. They have two parts: an inline part, and a definition stored elsewhere in the file.

The inline part uses two sets of brackets. The first surrounds the text that should appear linked; the second holds a label pointing at the definition. A space between the two sets is allowed, and the label is not case sensitive — it can include letters, numbers, spaces, or punctuation:

[hobbit-hole][1]

The definition is the label in brackets, followed immediately by a colon and at least one space, then the URL (optionally in angle brackets), then an optional title in double quotes, single quotes, or parentheses:

[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle "Hobbit lifestyles"

The definition can go anywhere in the document — immediately after the paragraph that uses it, or gathered at the end like endnotes. The rendered output is identical to an inline link:

In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends
of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to
eat: it was a [hobbit-hole][1], and that means comfort.

[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle "Hobbit lifestyles"

Link best practices#

Markdown applications don’t agree on how to handle spaces in the middle of a URL. For compatibility, URL-encode spaces with %20. Parentheses in the middle of a URL are also problematic; encode the opening parenthesis as %28 and the closing one as %29. Alternatively, use the HTML <a> tag.

Internal links on this site#

Never hand-type an internal URL. Use relref, which resolves the content path at build time and fails the build on a bad path — see Shortcodes. For choosing how to point readers at related pages, see Cross-references.

Tables#

Markdown itself does not support tables; it relies on HTML table elements unless the processor implements a superset that adds them:

• CommonMark
• GitHub Flavored Markdown (GFM)
• Markdown Extra
• MultiMarkdown
• R Markdown

Not all Markdown applications support these extended syntax elements — confirm which lightweight markup language the target supports.

To add a table, use the vertical line | to separate each column and three or more dashes --- to create each column’s header. Add a vertical line at either end of the row:

| Month    | Savings |
| -------- | ------- |
| January  | $250    |
| February | $80     |
| March    | $420    |

The output would look like:

Align text in the columns by adding a colon : to the left, right, or both sides of the dashes --- within the header row:

• :-- means the column is left aligned
• --: means the column is right aligned
• :-: means the column is centre aligned

| Item              | In Stock | Price |
| :---------------- | :------: | ----: |
| Python Hat        |   True   | 23.99 |
| SQL Hat           |   True   | 23.99 |
| Codecademy Tee    |  False   | 19.99 |
| Codecademy Hoodie |  False   | 42.99 |

Text can be formatted within tables: links, emphasis, and inline code (words or phrases in backticks only, not code blocks) all work. Headings, blockquotes, horizontal rules, images, lists, and HTML tags do not.

Display a pipe character inside a table by escaping it as \| or with its HTML character code |.

Definition lists#

Some Markdown processors allow definition lists of terms and their corresponding definitions. To create one, type the term on the first line. On the next line, type a colon followed by a space and the definition:

First Term
: This is the definition of the first term

Second Term
: This is one definition of the second term
: This is another definition of the second term

The HTML looks like this:

<dl>
  <dt>First Term</dt>
  <dd>This is the definition of the first term.</dd>
  <dt>Second Term</dt>
  <dd>This is one definition of the second term.</dd>
  <dd>This is another definition of the second term.</dd>
</dl>

Footnotes#

Footnotes add notes and references without cluttering the body of the document. A footnote reference renders as a superscript number linking to the note at the bottom of the page, and Hugo generates a back-link with a ↩ symbol so readers can jump from the footnote back to the original text. Footnotes via the Footnote extension are enabled by default.

Readers can click the link[^1] to jump to the content of the footnote.

[^1]: The footnote text goes here.

Definitions can be typed anywhere in the .md file; Hugo moves them to the very bottom of the rendered page. The exception is definitions placed inside other elements such as lists, block quotes, and tables, which do not move.

If a footnote needs to span multiple paragraphs, indent the subsequent paragraphs by four spaces or one tab and Hugo will keep them inside the footnote area.

To change how the footnote section looks, target the CSS classes .footnotes and .footnote-backref in the theme’s stylesheet.

Escaping characters#

To display a literal character that would otherwise be used to format text, add a backslash (\) in front of the character:

\* Without the backslash, this would be a bullet in an unordered list.

A backslash can escape the following characters:

Emoji#

There are two ways to add emoji to Markdown files: copy and paste the emoji into your Markdown-formatted text, or use the site’s emoji shortcode.

In most cases, you can copy an emoji from a source like Emojipedia and paste it into your document. Many Markdown applications display the emoji directly in the Markdown-formatted text. HTML and PDF exports should display the emoji too, as long as the document and output format support the character.

Some Markdown applications allow you to insert emoji by typing emoji shortcodes. These begin and end with a colon and include the name of an emoji:

Gone camping! :tent: Be back soon.
That is so funny! :joy:

Gone camping! ⛺ Be back soon.
That is so funny! 😂

Shortcode names vary by application. On this site, use the emoji shortcode, which reads the curated emoji table in data/series/ref/emojis.yml:

{{< emoji "warning" >}}

Which sources that table trusts for names, codepoints, and shortcodes is documented on the Writing mechanics page.