Markdown Guide

About Markdown#

Markdown is a lightweight markup language designed for readability and writability. Hugo uses it as the default content format. This page demonstrates the actual rendered appearance under the Neso theme; it is not intended to be a complete tutorial.

You may also want to read the Shortcodes page for Neso’s extended embedding options.

Headings#

Avoid using Heading 1 (#) inside Markdown body content; that level should be reserved for the page’s own title.

Markdown:

# Heading 1
## Heading 2
### Example of a Heading 3
#### Heading 4: use sparingly
##### Heading 5 is rarely useful
###### Heading 6 looks like body text

Rendered result:

Heading 1

Heading 2

Example of a Heading 3

Heading 4: use sparingly

Heading 5 is rarely useful

Heading 6 looks like body text

Paragraphs#

Just type to create paragraphs. Separate paragraphs with a blank line. The following is dummy text for layout demonstration.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

Bold and Italic#

Wrap with a single asterisk * for italic, double asterisks ** for bold, and triple for bold italic; you can also use strikethrough with ~~deleted~~.

Markdown:

This is normal text with *italic*, **bold**, ***bold italic***, and ~~strikethrough~~.

Rendered result:

This is normal text with italic, bold, bold italic, and strikethrough.

Blockquotes#

Start a line with > to create a blockquote; consecutive lines are grouped automatically. Use >> (or another >) for nested quotes.

Markdown:

> This is a single-level quote.
>
> It can span multiple paragraphs.
>
> > This is a nested quote (second level).

Rendered result:

This is a single-level quote.

It can span multiple paragraphs.

This is a nested quote (second level).

Neso also adds two enhancements for blockquotes:

Enhancement: Quote attribution#

Enable Markdown attributes in your hugo.toml:

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      [markup.goldmark.parser.attribute]
        block = true

Then place {author="Name" source="URL"} on the line immediately after the quote:

> This is a single-level quote.
{author="Neso" source="https://example.com"}

This renders an attribution and an optional source link:

This is a single-level quote.

Enhancement: GitHub Alerts#

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!NOTE] Custom Title
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Rendered result:

Note

Useful information that users should know, even when skimming content.

Custom Title

Useful information that users should know, even when skimming content.

Tip

Helpful advice for doing things better or more easily.

Important

Key information users need to know to achieve their goal.

Warning

Urgent info that needs immediate user attention to avoid problems.

Caution

Advises about risks or negative outcomes of certain actions.

Lists#

Use -, *, or + for unordered lists; use numbers with a period for ordered lists.

Markdown:

- Unordered item A
- Unordered item B
    + Sub-item B-1
    + Sub-item B-2

1. Ordered item one
2. Ordered item two
3. Ordered item three

Rendered result:

• Unordered item A
• Unordered item B
  • Sub-item B-1
  • Sub-item B-2

1. Ordered item one
2. Ordered item two
3. Ordered item three

Code: Block#

Markdown: wrap code with three backticks ` at the beginning and end (each on its own line):

```
package main

import "fmt"

func main() {
    for i := 0; i < 3; i++ {
        fmt.Println("Value of i:", i)
    }
}
```

Rendered result:

package main

import "fmt"

func main() {
    for i := 0; i < 3; i++ {
        fmt.Println("Value of i:", i)
    }
}

Use “Chroma” to enable syntax highlighting:

 2
 3
 4
 5
 6
 7
 8
 9
10

package main

import "fmt"

func main() {
    for i := 0; i < 3; i++ {
        fmt.Println("Value of i:", i)
    }
}

Terminal prompt symbol:

$

hugo server

Code: Inline#

Wrap text with a single backtick ` to display inline code:

const number = 42;

Use the syntax-highlighting shortcode:

Horizontal rules#

Three or more -, *, or _ produce a horizontal rule.

Markdown:

---
***
___

Rendered result (three rules):

Links#

Use [text](URL "optional title") for links.

Markdown:

This is a link: [Hugo website](https://gohugo.io "Go to Hugo official website").

Rendered result:

This is a link: Hugo website.

Images#

Use ![alt text](path "optional title"). The alt text helps with accessibility (a11y).

Markdown:

![Béton brut residential facade](beton-brut.jpg "Photo by babeneso")

Rendered result:

Footnotes#

Use [^id] to insert a footnote reference, and define it later in the document with [^id]: text.

Markdown:

This sentence has a footnote[^1].

[^1]: This is the footnote text, and it can include **bold** and *italic* formatting.

Rendered result:

This sentence has a footnote¹.