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 Pandoc which would cover everything I need (this article more than truly covers all the elements I would ever use).
How to adjust my SASS/SCSS styling so that the document would be rendered to suit my personal taste - for example tables.
Create a sample document with everything in it so that I could check that all of my styles worked properly.

The way I have written this article is to show the rendered text first such as this which will then be followed by the Pandoc 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

### H3 Heading

H4 italicised Heading

#### *H4 italicised Heading*

H5 Heading

##### H5 Heading

H6 Heading

###### H6 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 it is followed by two spaces at the end to create a hard break.
Which allows this second line to be in the same paragraph - this effectively adds a <br> tag at the end.

Inline Formatting

This text is italicized, bold, bold italicized, code and ~~strikethrough~~.

This text is *italicized*, **bold**, ***bold italicized***, `code` and ~~strikethrough~~

H₂O is a liquid. 2¹⁰ is 1024.

H~2~O is a liquid. 2^10^ is 1024.

Note that Pandoc does not support underlining and whilst underscores can be used in lieu of tildes, underscores are not supported by all markdown renderers.

Blockquotes

The blockquote element represents content that is quoted from another source, optionally with a citation which must be within a footer or cite element, and optionally with in-line changes such as annotations and abbreviations.

Blockquote without attribution

Tiam, ad mint andaepu dandae nostion secatur sequo quae. Note that you can use Markdown syntax within a blockquote.

Blockquote with attribution

Don’t communicate by sharing memory, share memory by communicating.
— Rob Pike¹

Tables

Pandoc table handling in Hugo is pretty crap. There’s basically no easy way to format them without using global CSS styles or pure html tables. Luckily I found a nice shortcode for this on Will Schenk’s website which I’ve modified slightly to work with Bootstrap and is covered in tables formatted with a custom shortcode.

There is however a big gotcha here. If you want to use Grid Layout tables you need to set the default defaultMarkdownHandler in your config file to pandoc otherwise the tables will not get rendered and using pandoc as the default handler results in the site taking 10 times as long.

Simple Tables

Simple table text alignment is based on the header position relative to the dashed line below. Also shown is a table caption.

Simple table syntax.
Right Aligned	Left Aligned	Centered	Default
Right1	Left1	Center1	Default1
Right2	Left2	Center2	Default2
Right3	Left3	Center3	Default3

  Right Aligned     Left Aligned      Centered     Default
---------------     --------------   ----------    -------
  Right1            Left1             Center1      Default1
  Right2            Left2             Center2      Default2
  Right3            Left3             Center3      Default3

Table:  Simple table syntax.

Grid Tables

Grid table with header row.
Right	Left	Centered
Bananasas	are yellow	Text without a hard break will be joined into a single line
Oranges	are Orange	Text with a hard break will not be joined
Avocados	are Green	Bullet points are Just bullets points!

+-----------+------------+---------------------------------+
| Right     | Left       | Centered                        |
+==========:+:===========+:===============================:+
| Bananas   | are yellow |  Text without a hard break will |
|           |            | be joined into a single line    |
+-----------+------------+---------------------------------+
| Oranges   | are Orange | Text with a hard break \        |
|           |            | will not be joined              |
+-----------+------------+---------------------------------+
| Avocados  | are Green  | - Bullet points are             |
|           |            | - Just bullets points!          |
+-----------+------------+---------------------------------+

: Grid table with header row.

Headerless Grid Tables

Headerless grid table.
Bananas	are yellow	built-in wrapper bright color
Oranges	are Orange	cures scurvy tasty

+----------:+:-----------+:------------------:+
| Bananas   | are yellow | - built-in wrapper |
|           |            | - bright color     |
+-----------+------------+--------------------+
| Oranges   | are Orange | - cures scurvy     |
|           |            | - tasty            |
+-----------+------------+--------------------+

: Headerless grid table.

Pipe tables with Inline Markdown

Inline	Markdown	in	Table
italics	bold	~~strikethrough~~	`code`

| Inline     | Markdown  |        in         | Table      |
| ---------- | --------- | ----------------- | ---------- |
| *italics*  | **bold**  | ~~strikethrough~~ | `code`     |

Tables formatted with a custom shortcode

With a custom shortcode you can use Bootstrap’s table styling properly. Wrap the table in the following shortcode using any of the Bootstrap table classes or other classes as you like {{< table “class1 class2” >}} Table Content {{< /table >}}

{ { < table “table table-striped table-bordered” > } } +———–+————+——————–+ | Right | Left | Centered | +==========:+:===========+:==================:+ | Bananas | are yellow | - built-in wrapper | | | | - bright color | +———–+————+——————–+ | Oranges | are Orange | - cures scurvy | | | | - tasty | +———–+————+——————–+ { { < /table > } }

+-----------+------------+--------------------+
| Right     | Left       | Centered           |
+==========:+:===========+:==================:+
| Bananas   | are yellow | - built-in wrapper |
|           |            | - bright color     |
+-----------+------------+--------------------+
| Oranges   | are Orange | - cures scurvy     |
|           |            | - tasty            |
+-----------+------------+--------------------+

HTML tables

If all else fails you can resort to an ugly html table.

#	First	Last	Handle
1	Mark	Otto	@mdo
2	Jacob	Thornton	@fat
3	Larry	the Bird	@twitter

<table class="table table-striped table-bordered">
  <thead>
    <tr>
      <th scope="col">#</th>
      <th scope="col">First</th>
      <th scope="col">Last</th>
      <th scope="col">Handle</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">1</th>
      <td>Mark</td>
      <td>Otto</td>
      <td>@mdo</td>
    </tr>
    <tr>
      <th scope="row">2</th>
      <td>Jacob</td>
      <td>Thornton</td>
      <td>@fat</td>
    </tr>
    <tr>
      <th scope="row">3</th>
      <td>Larry</td>
      <td>the Bird</td>
      <td>@twitter</td>
    </tr>
  </tbody>
</table>

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

List elements can be grouped together but the list itself must have a blank line above and below it. There should only be a single space after the bullet or number.

Ordered List

This is the first list:

First item
Second item
Third item

This is the second list:

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

This is the first list:

1. First item
2. Second item
3. Third item

This is the second list:

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

Auto numbered lists

The first item will be numbered (1).
The second item will be numbered (2).
The third item will be numbered (3).

#.  The first item will be numbered (1).
#.  The second item will be numbered (2).
#.  The third item will be numbered (3).

Unordered List

Unordered lists can start with a ‘-’, ‘+’ or ’*’ which is nice when you have indented lists as it makes it easier to read but you can also just indent the list by 2x spaces for each indent level.

Vegetable
- Fruits
  - Banana
  - Apple
  - Orange
- Vegetables
  - Broccoli
  - Tomato?
Mineral
- Rock
  - Sandstone
  - Limestone
- Metal
  - Copper
  - Zinc

* Vegetable
  + Fruits
    - Banana
    - Apple
    - Orange
  + Vegetables
    - Broccoli
    - Tomato?
* Mineral
  + Rock
    - Sandstone
    - Limestone
  + Metal
    - Copper
    - Zinc

OR with dashes only:

- Vegetable
  - Fruits
    - Banana
    - Apple
    - Orange
  - Vegetables
    - Broccoli
    - Tomato?
- Mineral
  - Rock
    - Sandstone
    - Limestone
  - Metal
    - Copper
    - Zinc

Nested list

Item
1. First Sub-item indented
2. Second Sub-item indented

* Item
  1. First Sub-item indented
  2. Second Sub-item indented

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.

For a more compact list use tildes:

Term 1

Definition 1

Term 2

Definition 2a
Definition 2b

Term 3

Definition 3

Nested Term 4: Nested Definition 4 - nested items need to be indented by 4x spaces
Nested Term 5: Nested Definition 5

Term 1
  ~ Definition 1

Term 2
  ~ Definition 2a  
    Definition 2b

Term 3
  ~ Definition 3

    Nested Term 4
    ~ Nested Definition 4  - nested items need to be indented by 4x spaces

    Nested Term 5
    ~ Nested Definition 5

Links

This is an internal link to the References section and this is a link to the Pandoc website.

This is an internal link to the [References](#references) section and this is a link to the [Pandoc](https://pandoc.org) website.

Images

With images you can specify any attribute you like. In this case this text flows around the right hand side of the image.

![Image Caption](/gallery/2017/2017_01_7-8/20170107-_O156345_DxO.jpg "Alt Text"){class="img-fluid mb-3 mr-3 float-left" width="50%"}

With images you can specify any attribute you like. In this case this text should flow around the right hand side of the image.

You will also need to add a <div class="clearfix"></div> element to prevent subsequent text such as the References section below from flowing around the image.

References

This is a reference

As stated in (1) …

Footnotes

And almost finally ² this is a footnote which will be displayed at the bottom of this page.

And almost finally [^note1] this is a footnote which will be displayed at the bottom of this page.

[^note1]: Note that the footnote marker must not contain any whitespace.

Other Elements — abbr, kbd, mark

GIF is a bitmap image format.

Press CTRL+ALT+Delete to end the session.

Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures.

The above quote is excerpted from Rob Pike’s talk during Gopherfest, November 18, 2015.↩︎
Note that the footnote marker must not contain any whitespace.↩︎