# 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.
### 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 `
` tag within a single `` element. This keeps lines close together.
2. **Paragraph** (Double Enter/Empty Line):
Renders as two separate `
` 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 `
` tag, this is often the root cause. You can verify the rendered output using the [CommonMark dingus](https://spec.commonmark.org/dingus/).
### 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 `
` tag.
---
## Hugo Shortcodes
Shortcodes are used to insert complex HTML components that standard Markdown cannot describe. Hugo utilizes two [distinct syntaxes](https://gohugo.io/content-management/shortcodes/#notation) based on how the content should be processed.
- `{{}}`: **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.
> **Note**: Using `{{%/* */%}}` for raw HTML components may lead to unintended rendering errors if the internal HTML conflicts with Markdown rules.