This article offers a sample of basic Markdown syntax that can be used in Hugo content files, also it shows whether basic HTML elements are decorated with CSS in a Hugo theme.

John Gruber, the author of Markdown, puts it like this:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email. John Gruber

Without further delay, let us go over the main elements of Markdown and what the resulting HTML looks like:

Paragraphs

In Markdown your content usually spans the whole available document width. This is called a block. Blocks are always separated by whitespace to their adjacent blocks in the resulting document.

Any text not starting with a special sign is written as normal, plain text paragraph block and must be separated to its adjacent blocks by empty lines.

1
2
3

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.

Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Headings

A good idea is to structure your content using headings and subheadings. HTML-headings from h1 through h6 are constructed with a # for each level.

In Hugo you usually don’t use h1 as this is generated by your theme and you should only have one such element in a document.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# h1 Heading

## h2 Heading

### h3 Heading

#### h4 Heading

##### h5 Heading

###### h6 Heading

Horizontal Rules

To further structure your content you can add horizontal rules. They create a “thematic break” between paragraph blocks. In Markdown, you can create it with three consecutive dashes ---.

1
2
3
4
5

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.

---

Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Text Markers

Bold

You can show importance of a snippet of text with a heavier font-weight by enclosing it with two asterisks **.

1

I am rendered with **bold text**

Italics

You can emphasize a snippet of text with italics by enclosing it with underscores _.

1

I am rendered with _italicized text_

Strikethrough

In GFM (GitHub Flavored Markdown) you can do strikethroughs by enclosing text with two tildes ~~.

1

~~Strike through this text~~

Text substitution

This Markdown dialect supports an extension to combine multiple punctuation characters to single typographic entities. This will only be applied to text outside of code blocks or inline code.

1
2
3
4
5
6
7

Double quotes `"` and single quotes `'` of enclosed text are replaced by **"double curly quotes"** and **'single curly quotes'**.

Double dashes `--` and triple dashes `---` are replaced by en-dash **--** and em-dash **---** entities.

Double arrows pointing left `<<` or right `>>` are replaced by arrow **<<** and **>>** entities.

Three consecutive dots `...` are replaced by an ellipsis **...** entity.

Lists

Unordered

You can write a list of items in which the order of the items does not explicitly matter.

It is possible to nest lists by indenting an item for the next sublevel.

You may use any of -, * or + to denote bullets for each list item but should not switch between those symbols inside one whole list.

1
2
3
4
5
6
7
8

- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
  - Vestibulum laoreet porttitor sem
  - Ac tristique libero volutpat at
- Nulla volutpat aliquam velit
  - Phasellus iaculis neque
  - Purus sodales ultricies
- Faucibus porta lacus fringilla vel

Ordered

You can create a list of items in which the order of items does explicitly matter.

It is possible to nest lists by indenting an item for the next sublevel.

Markdown will automatically number each of your items consecutively. This means, the order number you are providing is irrelevant.

1
2
3
4
5
6
7
8

1. Lorem ipsum dolor sit amet
3. Consectetur adipiscing elit
    1. Integer molestie lorem at massa
    7. Facilisis in pretium nisl aliquet
99. Nulla volutpat aliquam velit
    1. Faucibus porta lacus fringilla vel
    1. Aenean sit amet erat nunc
17. Eget porttitor lorem

Tasks

In GFM (GitHub Flavored Markdown) you can add task lists resulting in checked or unchecked non-clickable items

1
2
3
4
5

- [x] Basic Test
- [ ] More Tests
  - [x] View
  - [x] Hear
  - [ ] Smell

Code

Inline Code

Inline snippets of code can be wrapped with backticks `.

1

In this example, `<div></div>` is marked as code.

Indented Code Block

A simple code block can be generated by indenting several lines of code by at least two spaces.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

Be impressed by my advanced code:

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

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

Fenced Code Block

If you want to gain more control of your code block you can enclose your code by at least three backticks ``` a so called fence.

In GFM (GitHub Flavored Markdown) you can also add a language specifier directly after the opening fence, ```js, and syntax highlighting will automatically be applied according to the selected language in the rendered HTML.

See Syntax Highlighting for additional documentation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

```js
grunt.initConfig({
  assemble: {
    options: {
      assets: 'docs/assets',
      data: 'src/data/*.{json,yml}',
      helpers: 'src/custom-helpers.js',
      partials: ['src/partials/**/*.{hbs,md}']
    },
    pages: {
      options: {
        layout: 'default.hbs'
      },
      files: {
        './': ['src/templates/pages/index.hbs']
      }
    }
  }
};
```

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

grunt.initConfig({
  assemble: {
    options: {
      assets: 'docs/assets',
      data: 'src/data/*.{json,yml}',
      helpers: 'src/custom-helpers.js',
      partials: ['src/partials/**/*.{hbs,md}']
    },
    pages: {
      options: {
        layout: 'default.hbs'
      },
      files: {
        './': ['src/templates/pages/index.hbs']
      }
    }
  }
};

Internal highlight shortcode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{{< highlight html >}}

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>
{{< /highlight html >}}

results are as followed:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

Tables

In GFM (GitHub Flavored Markdown) you can create tables by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned.

1
2
3
4
5

| Option | Description |
| ------ | ----------- |
| data   | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext    | extension to be used for dest files. |

Aligned Columns

Adding a colon on the left and/or right side of the dashes below any heading will align the text for that column accordingly.

1
2
3
4
5

| Option | Number | Description |
| ------:|:------:|:----------- |
| data   | 1      | path to data files to supply the data that will be passed into templates. |
| engine | 2      | engine to be used for processing templates. Handlebars is the default. |
| ext    | 3      | extension to be used for dest files. |

Inline Markdown within tables

1
2
3
4
5
6

| Name              | Markdown            | HTML tag             |
| ----------------- | ------------------- | -------------------- |
| *Emphasis*        | `*Emphasis*`        | `<em></em>`          |
| **Strong**        | `**Strong**`        | `<strong></strong>` |
| `code`            | ``code``            | `<code></code>`      |
| ~~Strikethrough~~ | `~~Strikethrough~~` | `<del></del`         |

Blockquotes

For quoting blocks of content from another source within your document add > before any text you want to quote.

Blockquotes can also be nested.

1
2
3
4
5

> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.
>
> > Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
>
> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.

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¹

Links

Autolink

In GFM (GitHub Flavored Markdown) absolute URLs will automatically be converted into a link.

1

This is a link to https://example.com.

Basic Link

You can explicitly define links in case you want to use non-absolute URLs or want to give different text.

1

[Assemble](http://assemble.io)

Link with Tooltip

For even further information, you can add an additional text, displayed in a tooltip on hovering over the link.

1

[Upstage](https://github.com/upstage/ "Visit Upstage!")

Link References

Links can be simplyfied for recurring reuse by using a reference ID to later define the URL location. This simplyfies writing if you want to use a link more than once in a document.

1
2
3

[Example][somelinkID]

[somelinkID]: https://example.com "Go to example domain"

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 and a footnote definition that will be placed in a list of footnotes.

Usually the list of footnotes will be shown at the end of your document. If we use a footnote in a notice box it will instead be listed at the end of its box.

Footnotes can contain block elements, which means that you can put multiple paragraphs, lists, blockquotes and so on in a footnote. It works the same as for list items, just indent the following paragraphs by four spaces in the footnote definition.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

That's some text with a footnote[^1]

[^1]: And that's the footnote.

That's some more text with a footnote.[^someid]

[^someid]:
    Anything of interest goes here.

    Blue light glows blue.

That’s some text with a footnote²

That’s some more text with a footnote.³

Images

Images have a similar syntax to links but include a preceding exclamation mark.

1

![Spock](https://octodex.github.com/images/spocktocat.png)