Part 1: Standard Markdown Syntax (CommonMark)

This is the universal syntax that works almost everywhere.

1. Headings

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

2. Text Formatting

This text will be italic. This will also be italic.

This text will be bold. This will also be bold.

This text will be strikethrough.

This text will be bold and italic.

3. Paragraphs & Line Breaks

Paragraphs are separated by a blank line.

To force a hard line break (a ) without starting a new paragraph, end a line with two or more spaces.

This line has two spaces at the end.

This line will appear directly below it.

4. Blockquotes

Use the > character to create a blockquote.

This is a blockquote.

This is a nested blockquote.

Renders as:

This is a blockquote.

This is a nested blockquote.

5. Lists

Unordered Lists

Use *, -, or + interchangeably.

• Item 1
• Item 2
  • Nested Item 2a
  • Nested Item 2b

• Item 3

Ordered Lists

Numbers are sequential. The actual number you type doesn’t matter, only that it’s a number followed by a period.

1. First item

2. Second item

3. Third item (this will render as “3.”)

   1. Sub-item (this will render as “3a.”)

4. Code

Inline Code

Wrap code with single backticks (`).

Use the printf("hello, world"); function to get started.

Fenced Code Blocks

Use triple backticks (```) for blocks of code. Specify a language for syntax highlighting.

package main

import "fmt"

func main() {
    fmt.Println("Hello, Hugo!")
}

7. Links

Inline Links

The most common way to link.

This is the link text

Reference Links

Good for keeping your writing clean and re-using links.

You can read more about Hugo here. And you can find themes here.

8. Images

Syntax is just like links, but with a ! at the beginning.

9. Horizontal Rules

Create a thematic break () with three or more asterisks, dashes, or underscores.

10. Escaping Characters

Use a backslash () to “escape” a special character and render it literally.

*This is not italic, it’s literally an asterisk.*

Part 2: Extended Markdown (Hugo’s Goldmark)

Hugo’s default renderer, Goldmark, supports extra features.

1. Tables

: on the left (:—) means left-align.

on both sides (:–:) means center-align.

on the right (—:) means right-align.

2. Task Lists

Useful for “to-do” items.

• Complete the guide
• Add more shortcodes
• Deploy the site

Renders as:

[x] Complete the guide

[ ] Add more shortcodes

[ ] Deploy the site

3. Footnotes

Here is some text with a footnote.¹ And here is another.²

4. Definition Lists

Term 1

Definition 1

Term 2

Definition 2a

Definition 2b

Part 3: Hugo Shortcodes

Shortcodes are your escape hatch from Markdown’s limitations. They let you run Hugo functions or inject complex HTML.

Shortcode Syntax

There are two main types:

The content inside the shortcode is processed as Markdown.

Key Built-in Shortcodes

Here are the most useful shortcodes that come with Hugo.

figure

The correct way to add images. It creates an HTML5 element, allowing for captions, alt text, and more.

youtube

Embeds a responsive YouTube video.

vimeo

Embeds a responsive Vimeo video.

ref and relref

CRITICAL for internal linking. These shortcodes create a guaranteed correct link to another piece of content, even if you change its URL in the future. Hugo will warn you if the link breaks.

ref: Generates a full, absolute permalink.

relref: Generates a relative permalink.

Read my about page.

details

Creates a collapsible block.

Gallery Shortcode

×