Markdown Syntax Guide

Sample article showcasing basic Markdown syntax and formatting.

January 1, 2020 Markdown (2)Syntax (2)Example (4)Guide (8)1049 words 5 min FreeCAD (29)

a cover alternative title — a cover caption

Hugo supports Markdown syntax for formatting text, creating lists, and more.

This article offers a sample of basic Markdown syntax that can be used in Hugo content files and its rendered output with the current Theme.

Headings

Markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

### Heading with custom style {style="color: purple; background: coral; padding: 0.5rem;"}

### Heading with a custom id {#custom-id}

How it renders:

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Heading with custom style

Heading with a custom id

Emphasis

Markdown
*This text will be italic*
_This will also be italic_

**This text will be bold**
__This will also be bold__

_You **can** combine them_

How it renders:

This text will be italic

This will also be italic

This text will be bold

This will also be bold

You can combine them

Lists

Unordered

Markdown
- Item 1
- Item 2
  - Item 2a
  - Item 2b

How it renders:

Item 1
Item 2
- Item 2a
- Item 2b

Ordered

Markdown
Item 1
Item 2
Item 3
Item 3a
Item 3b

How it renders:

Item 1
Item 2
Item 3
1. Item 3a
2. Item 3b

Task list

Markdown
- [x] Write documentation
- [ ] Review code
- [ ] Deploy changes

How it renders:

Write documentation
Review code
Deploy changes

Definition list

Markdown
First Term
: This is the definition of the first term.

Second Term
: This is the definition of the second term.

How it renders:

First Term: Lorem est tota propiore conpellat pectoribus de pectora summo. Redit teque digerit hominumque toris verebor lumina non cervice subde tollit usus habet Arctonque, furores quas nec ferunt. Quoque montibus nunc caluere tempus inhospita parcite confusaque translucet patri vestro qui optatis lumine cognoscere flos nubis! Fronde ipsamque patulos Dryopen deorum.
Second Term: This is the definition of the second term.

Images

Markdown
![](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

How it renders:

With caption:

Markdown
![landscape](https://fastly.picsum.photos/id/1044/800/600.jpg?hmac=aNJNCvHzwwgQQWDUJPUFUAyd5LYhh8cAPIawaBtti3c "Lorem Picsum")

How it renders:

For more advanced functionality, use Hugo’s built-in Figure shortcode.

Links

Markdown
[Hugo](https://gohugo.io)

[News Section](/news)

[Heading ID](#custom-id)

How it renders:

Hugo

News Section NewsBrowse the latest news

Heading ID

Styling Text

Style	Syntax	Example output
Bold	`bold`	Some bold text
Italic	`italic`	Some italic text
Deleted	`~~deleted~~`	Some ~~deleted~~ text
Inserted	`++inserted++`	Some inserted text
Subscript	`~subscript~`	Some _subscript text
Superscript	`^superscript^`	Some ^superscript text

Blockquotes

Markdown
> As Newton said:
>
> If I have seen further it is by standing on the shoulders of Giants.

How it renders:

Quote
As Newton said:
If I have seen further it is by standing on the shoulders of Giants.

Blockquote with attribution

Markdown
> Don't communicate by sharing memory, share memory by communicating.
> — <cite>Rob Pike[^1]</cite>

[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.

Markdown
> Programs must be written for people to read, and only incidentally for machines to execute.
{cite="https://web.mit.edu/6.001/6.037/sicp.pdf" caption="**Harold Abelson & Gerald Jay Sussman**, *Structure and Interpretation of Computer Programs*"}

How it renders:

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

Quote
Programs must be written for people to read, and only incidentally for machines to execute.

Harold Abelson & Gerald Jay Sussman, Structure and Interpretation of Computer Programs

Inline Code

Markdown
Inline `code` has `back-ticks around` it.

How it renders:

Inline code has back-ticks around it.

Code Blocks

Syntax Highlighting

Markdown
```go
func main() {
    fmt.Println("Hello World")
}
```

How it renders:

func main() {
    fmt.Println("Hello World")
}

Code block with backticks and language specified

Markdown
```html {linenos=true}
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <title>Example HTML5 Document</title>
        <meta name="description" content="Sample article showcasing basic Markdown syntax and formatting for HTML elements.">
    </head>
    <body>
        <p>Test</p>
    </body>
</html>
```

How it renders:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <title>Example HTML5 Document</title>
        <meta name="description" content="Sample article showcasing basic Markdown syntax and formatting for HTML elements.">
    </head>
    <body>
        <p>Test</p>
    </body>
</html>

Code block with Hugo’s internal highlight shortcode

Markdown
{{< highlight html >}}

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <title>Example HTML5 Document</title>
        <meta name="description" content="Sample article showcasing basic Markdown syntax and formatting for HTML elements.">
    </head>
    <body>
        <p>Test</p>
    </body>
</html>

{{< /highlight >}}

How it renders:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <title>Example HTML5 Document</title>
        <meta name="description" content="Sample article showcasing basic Markdown syntax and formatting for HTML elements.">
    </head>
    <body>
        <p>Test</p>
    </body>
</html>

Tables

Markdown
| Syntax    | Description |
| --------- | ----------- |
| Header    | Title       |
| Paragraph | Text        |

How it renders:

Syntax	Description
Header	Title
Paragraph	Text

Inline Markdown within tables and alignment

Markdown
| Italics   | Bold     | Code   |
| :-------- | :------: | -----: |
| _italics_ | **bold** | `code` |

How it renders:

Italics	Bold	Code
italics	bold	`code`

Alerts

Alerts are a Markdown extension based on the blockquote syntax that you can use to emphasize critical information. GitHub-style alerts are supported. Please make sure you are using Hugo v0.146.0 or later.

Markdown
> [!NOTE]
> 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.

How it renders:

Note
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.

Other Elements

Markdown
<abbr title="Graphics Interchange Format">GIF</abbr> is a bitmap image format.

GIF is a bitmap image format.

Markdown
H~2~O

H₂O

Markdown
X^n^ + Y^n^ = Z^n^

Xⁿ + Yⁿ = Zⁿ

Markdown
Press <kbd>CTRL</kbd> + <kbd>ALT</kbd> + <kbd>Delete</kbd> to end the session.

Press CTRL + ALT + Delete to end the session.

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

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

Configuration

Hugo uses Goldmark for Markdown parsing. Markdown rendering can be configured in hugo.yaml under markup.goldmark.

See Hugo documentation on Configure Markup.

Learning Resources

The above quote is excerpted from Rob Pike’s talk during Gopherfest, November 18, 2015. ↩︎

Hi there! Internet Explorer is no longer supported.

Markdown Syntax Guide

Sample article showcasing basic Markdown syntax and formatting.

Headings

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Heading with custom style

Heading with a custom id

Emphasis

Lists

Unordered

Ordered

Task list

Definition list

Images

Links

Styling Text

Blockquotes

Blockquote with attribution

Inline Code

Code Blocks

Syntax Highlighting

Code block with backticks and language specified

Code block with Hugo’s internal highlight shortcode

Tables

Inline Markdown within tables and alignment

Alerts

Other Elements

Configuration

Learning Resources