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:
- 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 此標題的連結
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.
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.