A thematic break signals a shift in topic or scene within a section, rendered as a horizontal rule across the page. It is written as three or more -, *, or _ characters on a line of their own, with optional spaces between them.
Content before the break.
---
Content after the break.
Content before the break.
Content after the break.
Best Practice
- Use
---as the standard form — it is the most widely recognised and readable in source. - Always surround the thematic break with blank lines. Without a blank line above,
---can be misread as a setext heading underline by some parsers. - Use thematic breaks sparingly; overuse fragments a document unnecessarily.
Notes
Setext Heading Ambiguity
The --- syntax doubles as the setext underline for a level-two heading. A parser will interpret --- as a heading underline if it immediately follows a non-empty line of text with no intervening blank line:
This becomes a heading
---
This is a thematic break because there is a blank line above.
---
Always leave a blank line before --- when you intend a thematic break rather than a heading. The *** and ___ forms carry no such ambiguity.
Alternative Forms
All three of the following are valid and produce identical output:
---
***
___
Spaces between characters are also permitted:
- - -
* * *
Markdown Flavour Support
Supported by all major flavours.
Flavour Support Detail
| Flavour | Support | Notes |
|---|---|---|
| Original Markdown | Yes | All three character forms defined in the original spec. |
| CommonMark | Yes | Precisely specifies the setext ambiguity rule; blank line before --- is required for a thematic break. |
| GitHub Flavored Markdown | Yes | Inherits CommonMark rules. |
| Pandoc Markdown | Yes | All forms supported; output varies by conversion target. |
Practical Examples
- Scene break in a short story: Use
---to signal a jump in time or location without adding a new heading — the conventional scene-break marker in prose.
Sarah locked the door behind her and did not look back.
---
Three years later, the house stood empty.
Sarah locked the door behind her and did not look back.
Three years later, the house stood empty.
- Dividing a travel blog post: Separate the distinct parts of a long post — arrival, the day out, dinner — without introducing a new heading level.
We landed at six in the morning, exhausted but excited.
---
By noon we had eaten twice and found the best coffee in the city.
We landed at six in the morning, exhausted but excited.
By noon we had eaten twice and found the best coffee in the city.
- Separating two loose sections in a personal wiki: When two blocks of notes belong on the same page but are not closely related, a thematic break creates breathing room without the formality of a heading.
Books to read this year:
- The Goldfinch — Donna Tartt
- Piranesi — Susanna Clarke
---
Films recommended by friends:
- Past Lives
- The Holdovers
Books to read this year:
- The Goldfinch — Donna Tartt
- Piranesi — Susanna Clarke
Films recommended by friends:
- Past Lives
- The Holdovers