Writing

Markdown syntax

Every element CommonMark and GitHub Flavored Markdown produce, as the theme renders it.

3 min read

This page is a page bundle - a directory with an index.md - so the image further down sits beside it and is referenced by its file name.

Headings

h2 to h4 appear in the table of contents on the right, which is the theme’s default (markup.tableOfContents). The page title is the only h1, so start the body at ##.

Heading level 2

Heading level 3

Heading level 4

Heading level 5

Heading level 6

Paragraphs

A paragraph is one or more lines of text separated by a blank line. The column is capped at a comfortable measure, so long lines wrap at a length that reads well on a wide screen.

A second paragraph. A line ending in two spaces or a backslash
breaks without starting a new paragraph.

Emphasis

Markdown	Result
`bold`	bold
`_italic_`	italic
`*both*`	both
`~~struck~~`	~~struck~~
`code`	`code`
`<kbd>Ctrl</kbd>`	`Ctrl` + `K`
`<mark>marked</mark>`	marked
`H<sub>2</sub>O`, `x<sup>2</sup>`	H₂O, x²

Blockquotes

A blockquote is a paragraph prefixed with >.
It can hold several paragraphs, emphasis, code and links .
And a nested quote.

Lists

Unordered

First item
Second item
- Nested item
- Another nested item
  - Deeper still
Third item

Ordered

Install the theme
Configure the site
1. Set baseURL
2. Set theme
Write pages

Task list

Copy the theme
Write the example site
Publish it

Definition list

Front matter: The block of YAML, TOML or JSON at the top of a content file.
Page bundle: A directory holding an index.md and the files that belong to it.

Links

Kind	Markdown
A page, by path	`/getting-started/configuration`
A page, relative	`../shortcodes`
A heading on this page	`#tables`
A heading on another page	`/writing/code-blocks#line-numbers`
Absolute	`https://gohugo.io`
Autolink	https://gohugo.io
Email	hello@example.org

A link with a title shows it on hover: Hugo .

A footnote reference looks like this.¹ Another one.²

Images

A diagram of a page holding three lines of text

An image can also come from static/ by an absolute path, or from anywhere by URL.

Tables

Columns are aligned with colons in the separator row:

Setting	Type	Default	Description
`sidebarCollapsible`	bool	`true`	Sections can be collapsed
`sidebarCollapsed`	bool	`false`	Sections start collapsed
`externalLinksNewTab`	bool	`false`	Absolute links open in a new tab
`landing`	bool	`false`	Home page is the hero

A table wider than the column scrolls on its own instead of sliding under the table of contents:

Environment variable	Config key	Type	Default	Applies to	Description
`APP_SERVER_PUBLIC_URL`	`server.public_url`	string	`http://localhost:3000`	every node	The address users reach the service at, used to build links in outgoing mail
`APP_DATABASE_REPLICA_DSNS`	`database.replica_dsns`	list	empty	api	Read replicas, tried in order

Code

Inline code sits in the sentence. A block is fenced with three backticks and a language:

package main

import "fmt"

func main() {
	fmt.Println("hello")
}

Horizontal rule

Three dashes on their own line:

Inline HTML

The example site sets markup.goldmark.renderer.unsafe = true, so HTML passes through:

A native details element

Its content is markdown, as long as a blank line separates it from the tags.

Escaping

Prefix a character with a backslash to print it literally: *not emphasis*, `not code`, # not a heading.

The footnote text is collected at the end of the page. ↩︎
A footnote label may be a word. ↩︎