Semantic Markdown Link to this heading
In static site generation, Markdown is not merely a shorthand for text; it is a direct instruction for generating HTML. Hugo follows the CommonMark (external link) specification via the Goldmark engine. Understanding the underlying HTML output is essential for precise layout control.
Useful links:
- CommonMark playground (external link)
- CommonMark spec (external link)
Paragraphs vs. Line Breaks Link to this heading
The visual distance between lines is determined by the generated HTML tags, which are influenced by your Markdown syntax:
- Soft Line Break (Double Space):
Renders as a
<br>tag within a single<p>element. This keeps lines close together. - Paragraph (Double Enter/Empty Line):
Renders as two separate
<p>elements.
Major CSS frameworks set paragraphs with greater vertical spacing than soft line breaks. If you observe unexpectedly wide spacing, check whether your Markdown syntax is generating a <p> tag, this is often the root cause.
List Item Link to this heading
To include multi-line content (like code blocks) inside a list item, you must maintain consistent indentation:
- Incorrect: Placing a code block immediately after a list item without indentation will break the list into two separate entities.
- Correct: Indenting the nested content with four spaces ensures it remains semantically bound to the parent
<li>tag.
Hugo Shortcodes Link to this heading
Shortcodes are used to insert complex HTML components that standard Markdown cannot describe. Hugo utilizes two distinct syntaxes (external link) based on how the content should be processed.
{{< name >}}: Standard notation.. The content inside is treated as raw HTML and is not parsed by the Markdown engine.{{% name %}}: Markdown notation.. The content inside is sent back to the Markdown engine to be parsed into HTML.
When using Markdown notation, avoid indenting content inside the shortcode by four or more spaces. Per the CommonMark specification, four-space indentation is treated as a code block.