Markdown

With Hugo, you write your documentation in markdown, which is a lightweight syntax for formatting text.

Writing with markdown is much simpler than writing in HTML, allowing you to format your documentation easily as text, headers, lists, images, links, and code blocks, using any text editor.

As an example, below is some markup that displays a level 2 header, a paragraph of text, a level 3 header, and a simple bulleted list. You can see how simple and intuitive it is.

## This is a level 2 header
This is a paragraph of text. Some is **bold** and some is _italicized_.

## To Do
- Buy snacks
- Eat snacks

And here is the HTML that Hugo generates from that markdown. You could’ve written this HTML yourself, but it’s simpler and easier to work with markdown.

<h2 id="this-is-a-level-2-header">This is a level 2 header</h2>
<p>This is a paragraph of text. Some is <strong>bold</strong> and some is <em>italicized</em>.</p>
<h2 id="to-do">To Do</h2>
<ul>
<li>Buy snacks</li>
<li>Eat snacks</li>
</ul>

And finally, here is what the output looks like in the browser. (The output is displayed in a blockquote here, so it has a different background color than usual.)

This is a level 2 header

This is a paragraph of text. Some is bold and some is italicized.

To Do

• Buy snacks
• Eat snacks

Avoid using uppercase in relative markdown links

By default, Hugo converts all HTML filenames to lowercase when it translates your markdown into HTML.

For example, Hugo will convert a markdown path named OpenIDConnectOAuth to an HTML path named openidconnectoauth.

This means that relative links in your site (i.e. links from your site to other documents in your site) must use lowercase characters, even if the markdown path used uppercase characters.

Alternatively, you can turn off the lowercase URL conversion by setting disablePathToLower to a value of true in your Hugo config file.