Headings

To create a heading, add number signs (#) in front of a word or phrase. The number of number signs (#) you use should correspond to the heading level.

For example, to create a heading level three (<h3>), use three number signs (e.g., ### My Header).

# Header 1

## Header 2

### Header 3

#### Header 4

##### Header 5

###### Header 6

Headings - Best Practices

You should also put blank lines before and after a heading for compatibility.

Try to put a blank line before...

# Heading

...and after a heading.

Also on simple detail page’s you should generally not use a Heading 1 in the content for SEO purposes. This is because the main title of the page is already a Heading 1.

Heading - Custom Ids

By default Hugo adds the slugified header as the id. For instance: “Heading 2” becomes id ‘heading-2’. Providing a custom id allows you to override the automatically generated id, and can be linked to using the custom id as a URL fragment (e.g. .../url/path/page#custom-id).

To add a custom heading ID, enclose the custom ID in curly braces on the same line as the heading.

### My Great Heading {#custom-id}

You can link to headings with (custom) IDs in the file by creating a standard link with a hash sign (#) followed by the custom heading ID. These are commonly referred to as anchor links.

[Go to Custom Id Header](#custom-id)

Paragraphs

To create paragraphs, use a blank line to separate one or more lines of text.

I really like using Markdown.

I think I'll use it to format all of my documents from now on.

Paragraphs - Best Practices

Don’t put tabs or spaces in front of your paragraphs.

Keep lines left-aligned like this.

Line Breaks

To create a line break or new line (<br>), end a line with two or more spaces, and then type return. You can also use the <br> HTML tag. And another option is typing a backslash (\) at the end of the line.

This is the first line.\
And this is the second line.

Line Breaks - Best Practices

You can use two or more spaces (commonly referred to as “trailing whitespace”) for line breaks in nearly every Markdown application, but it’s controversial. It’s hard to see trailing whitespace in an editor, and many people accidentally or intentionally put two spaces after every sentence.

For this reason, you may want to use something other than trailing whitespace for line breaks. If your Markdown application supports HTML, you can use the <br> HTML tag. Another option is typing a backslash (\) at the end of the line.

Emphasis

You can add emphasis by making text bold or italic.

Bold

To bold text, add two asterisks or underscores before and after a word or phrase. To bold the middle of a word for emphasis, add two asterisks without spaces around the letters.

I just love **bold text**.

I just love __bold text__.

Love **is** bold

Italic

To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word for emphasis, add one asterisk without spaces around the letters.

Italicized text is the *cat's meow*.

Italicized text is the _cat's meow_.

A *cat* meow

Both Bold and Italic

To emphasize text with bold and italics at the same time, add three asterisks or underscores before and after a word or phrase. To bold and italicize the middle of a word for emphasis, add three asterisks without spaces around the letters.

This text is ***really important***.

This text is ___really important___.

This text is __*really important*__.

This text is **_really important_**.

This is really ***very important*** text.

Code

To denote a word or phrase as code, enclose it in backticks (`).

At the command prompt, type `nano`.

Strikethrough

You can strikethrough words by putting a horizontal line through the center of them. This feature allows you to indicate that certain words are a mistake not meant for inclusion in the document. To strikethrough words, use two tilde symbols (~~) before and after the words.

~~The world is flat.~~ We now know that the world is round

Links

To create a link, enclose the link text in brackets (e.g., [Cue lang]) and then follow it immediately with the URL in parentheses (e.g., (https://https://cuelang.org)).

My favorite project is [CUE](https://cuelang.org).

You can optionally add a title for a link. This will appear as a tooltip when the user hovers over the link. To add a title, enclose it in quotation marks after the URL.

My favorite project is [CUE](https://cuelang.org "CUElang.org").

Footnotes

The Markdown flavour understood by Hugo support footnotes. Each footnote is composed of two elements: the link to the footnote, and the footnote itself. The footnote gains an automatic link back to the initial link’s location on the page. Each link is a superscript number, linked to the relevant numbered footnote. The footnote source reference id must match between the footnote link and the footnote text, but the reference id isn’t exposed on the rendered page.

The footnote will appear at the end of the page, no matter where the footnote’s text is specified in the Markdown document. The footnote does need to be specified as a paragraph by itself, however, so it’s not a bad idea to specify the note immediately after the paragraph containing the link, so that context isn’t lost for the author.

Because the location of the footnote block can’t be controlled (and is at the bottom of the page, following the rendered document), consider including a “## Footnotes” H2-heading as the very last source line of any document that uses footnotes. This heading has been added to this page as an example.

Here’s an example of a footnote:

This is a link to a footnote.[^foo]
This is the sentence following the link to the footnote.

[^foo]: This is the footnote. It continues until the end of the paragraph.
This means that source newlines don't stop the footnote.
The entire paragraph is rendered at the bottom of the page.
One or more newlines can be inserted using the standard trailing-backslash mechanism ...\
\
... but they don't look *great*. Probably best avoided.

This is a new paragraph that's not part of the footnote.

This is a link to a footnote.¹ This is the sentence following the link to the footnote.

This is a new paragraph that’s not part of the footnote.

Escaping Characters

To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash (\) in front of the character.

\* Without the backslash, this would be a bullet in an unordered list.

Characters You Can Escape

You can use a backslash to escape the following characters.

Footnotes