While working on dark theme, I encountered confusing behavior when using multiple --- separators in a single .md file.
In markdown file the --- syntax is overloaded:
- At the very top of the file, it is interpreted as a delimiter for YAML front matter (metadata).
- Elsewhere in the document, it is interpreted as a horizontal rule (
<hr>).
This dual behavior leads to unexpected <hr> tags on the tutorials page
Problem:
When multiple --- blocks are used, especially near the top of the file, it becomes unclear whether they are treated as:
- additional YAML front matter blocks, or
- horizontal rules in rendered HTML
For example:
---
title: Example Page
---
Content starts here
---
More content
---
Expected behavior:
- First
--- block → YAML front matter
- Subsequent
--- → rendered as <hr>
Suggested improvements:
- Clarify documentation on how
--- is parsed (YAML vs <hr>)
- Warn or error when multiple YAML-like blocks are detected
- Provide linting guidance (e.g., markdownlint rules)
While working on dark theme, I encountered confusing behavior when using multiple
---separators in a single .md file.In markdown file the
---syntax is overloaded:<hr>).This dual behavior leads to unexpected
<hr>tags on the tutorials pageProblem:
When multiple
---blocks are used, especially near the top of the file, it becomes unclear whether they are treated as:For example:
Expected behavior:
---block → YAML front matter---→ rendered as<hr>Suggested improvements:
---is parsed (YAML vs<hr>)