Markdown and Hugo

Semantic Markdown

In static site generation, Markdown is not merely a shorthand for text; it is a direct instruction for generating HTML. Hugo follows the CommonMark specification via the Goldmark engine. Understanding the underlying HTML output is essential for precise layout control.

Useful links:

• CommonMark playground
• CommonMark spec

Paragraphs vs. Line Breaks

The visual distance between lines is determined by the generated HTML tags, which are influenced by your Markdown syntax:

1. Soft Line Break (Double Space): Renders as a <br> tag within a single <p> element. This keeps lines close together.
2. 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

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

Shortcodes are used to insert complex HTML components that standard Markdown cannot describe. Hugo utilizes two distinct syntaxes 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.