Markdown Syntax Guide for Hugo

This article started life as a cheatsheet for me as I was was trying to work out how my new website using Hugo - a framework for building websites, actually works:

  • How to write a document in Markdown which would cover everything I need (this article more than truly covers all the elements I would ever use).
  • Create a sample document with everything in it so that I could check that all of my styles worked properly.
  • Check that my custom shortcodes to hadndle responsive images, video and 360 panos work.

The way I have written this article is to show the rendered text first such as this which will then be followed by the Markdown syntax in this colour.

Headings

You can also use underlines for headings but I find the use of hashes easier so I’m sticking with them.

H1 Heading

# H1 Heading

H2 Heading

## H2 Heading

H3 Heading with emphasis

### H3 Heading with **emphasis**

H4 Heading

#### H4 Heading

Paragraphs

Here’s a line for us to start with.

This line is separated from the one above by two newlines, so it will be a separate paragraph.

This line is also a separate paragraph, but…
This line is only separated by a single newline followed by two spaces at the end to create a hard break, so it’s a separate line in the same paragraph.

This line is also a separate paragraph, but...__
This line is only separated by a single newline followed by two spaces at the end to create a hard break, so it's a separate line in the *same paragraph*.

Inline Formatting

This text is italicized with underscores, and this is italicized with asterisks.

This text is _italicized with underscores_, and this is *italicized with asterisks*.

This is strong emphasis and with underscores.

This is **strong emphasis** and __with underscores__.

This is italicized strong emphasis and with underscores but best practice is asterisks only.

This is ***strong emphasis*** and ___with underscores___ but best practice is asterisks only.

This is deleted text.

This ~~is deleted text.~~

Blockquotes

To create a blockquote add a > in front of a paragraph

Blockquotes are useful for highlighting something in an article

Note that you can use Markdown syntax within a blockquote and remember to add an extra > if you need a line break.

And this is a nested blockquote!

> Blockquotes are useful for highlighting something in an article
>
> **Note** that you can use *Markdown syntax* within a blockquote and remember to add an extra > if you need a line break.
>
>> And this is a nested blockquote!

Footnotes

This footnote will appear at the end of the article1

Footnotes can also be named however you like 2 but the naming will be ignored and the next number in sequence will be shown instead.

This footnote will appear at the end of the article[^1]

Footnotes can also be named however you like [^iamafish] but the naming will be ignored and the next number in sequence will be shown instead.

[^1]: This is the footnote that will appear at the end

[^iamafish]: Cod actually

Tables

Tables rendered in Hugo are pretty crap. There’s basically no easy way to format them without using global CSS styles for the table elements.

Italic defaultBold defaultStrikethrough defaultCode default
italicsboldstrikethroughcode
italicsboldstrikethroughcode
italicsboldstrikethroughcode
| Italic default | Bold default | Strikethrough default | Code default |
|----------------|--------------|-----------------------|--------------|
| *italics*      |**bold**      |~~strikethrough~~      |`code`        |
| *italics*      |**bold**      |~~strikethrough~~      |`code`        |
| *italics*      |**bold**      |~~strikethrough~~      |`code`        |
Italics leftCentred BoldStrikethrough defaultCode right
italicscentred boldstrikethroughthis is code
italicsboldstrikethroughcode
italicsboldstrikethroughcode
| Italics left | Centred Bold   | Strikethrough default | Code right    |
|:-------      | :-----:        |-----------------------|--------:      |
| *italics*    |**centred bold**|~~strikethrough~~      |`this is code` |
| *italics*    |**bold**        |~~strikethrough~~      |`code`         |
| *italics*    |**bold**        |~~strikethrough~~      |`code`         |

Code Blocks

Code block with backticks

Use 3x backticks at the start and end of the code block.

html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Code block indented with four spaces

Or indent it with 4x spaces

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Code block with Hugo’s internal highlight shortcode

Use Hugo’s highlight shortcode to highlight code, for example with html: {{< highlight html >}} a bunch of html code {{< /highlight>}}

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

List Types

Ordered List

This is the first list:

  1. First item
  2. Second item
  3. Third item
    1. Indented first item
    2. Indented second item
  4. Fourth item

This is the second list:

  1. Another first item - note that list numbering is taken from the first element (13)
  2. Another second item - subsequent list numbers are ignored (24)
  3. Another third item - and will be automatically incremented
This is the first list:

1. First item
2. Second item
3. Third item
   1. Indented first item
   2. Indented second item
4. Fourth item

This is the second list:

1.  Another first item which will continue from the previous list
2.  Another second item - subsequent list numbers are ignored (24)
3. Another third item - and will be automatically incremented

Unordered List

  • List item using +
  • Another item using -
  • And another item using * however just stick to the same symbol
+ List item using +
- Another item using -
* And another item using * however just stick to the same symbol

Nested list

  • Item
    • First Sub-item indented
    • Second Sub-item indented
- Item
  - First Sub-item indented
  - Second Sub-item indented

Mixed list type

  • Unordered Item
    1. First Sub-item indented
    2. Second Sub-item indented
  • Another unordered item
- Unordered Item
  1. First Sub-item indented
  2. Second Sub-item indented
- Another unordered item

Task list

  • an unchecked task list item
  • checked item
- [ ] an unchecked task list item
- [x] checked item

Definition List

Make sure there are 3x spaces between the : and the definition and 4x spaces for additional lines

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.

This is an internal link to the References section and this is a link to an external Markdown Guide .

This is an internal link to the [References](#references) section and this is a link to an external [Markdown Guide](https://www.markdownguide.org/basic-syntax/).

Images

Images in Markdown suck. You can only specify the Alt Text - no sizing so the image will appear full size. You can use Hugo’s figure shortcode, but again that is pretty limited as it doesn’t handle responsive images well, so I wrote my own figure shortcode to override Hugos.

Image Caption

![Image Caption](/gallery/2017/2017_01_7-8/20170107-_O156345_DxO-w1536.jpg "Alt Text")

Image with custom shortcode

This much better, class=“float-right” does what it is meant to do.

width=“50%” works nicely too.

By default my shortcode will generate a range of responsive JPG and WEBP sizes: 400px, 600px, 800px, 1024px, 1536px and 2048px.

{{< figure src="/gallery/2017/2017_01_7-8/20170107-_O156345_DxO.jpg" caption="Image with custom shortcode" class="float-right" width="50%" >}}

Panoramas

My custom shortcode for klrpano takes the source and the type is the xml file generated by krpano

Thurat Spires and Kanangra Walls Partial Panorama - 8 Feb 2015 - 53 MPixels

{{< krpano src="/panoramas/20150208-_O154434_DxO_panorama" caption="Thurat Spires and Kanangra Walls Partial Panorama - 8 Feb 2015 - 53 MPixels" type="pano" >}}

Videos

I have also created a video shortcode - which is simply the standard HTML video tag wrapped in a shortcode. Sizing is set by CSS:

{{< video src="/videos/Rocky_Creek_2012_Tambo_Pt1.mp4" type="video/mp4" >}}


  1. This is the footnote that will appear at the end ↩︎

  2. Cod actually ↩︎

What's on this page?