100% private — everything runs in your browser
Markdown Horizontal Line
Three dashes, stars, or underscores create a markdown horizontal line. Click each form, watch the divider render live, and copy the one you need.
MD Viewer Team
Text above the divider
Text below the divider
A markdown horizontal line — technically a thematic break — is a full-width divider that separates sections of a document. You make one by placing three or more dashes, asterisks, or underscores on their own line: ---, ***, or ___. The playground above lets you click each form and see the markdown horizontal line appear instantly, with the source on the left and the rendered divider on the right.
The syntax looks trivial, but two details trip people up. First, the line holding your markdown horizontal line needs a blank line before it — otherwise --- directly under text turns that text into a heading. Second, underscores cannot have spaces between them, while dashes and stars can. The Title ambiguity example in the playground demonstrates the heading trap live, so you can recognize it in your own files before it ships to a README.
Everything runs locally in your browser: edit the examples, add your own text above and below the divider, press Copy Markdown, and paste the working markdown horizontal line anywhere. Below the tool you will find the full syntax table, a step-by-step for inserting dividers cleanly, the Setext heading trap explained, and answers to the questions people ask most about horizontal rules.
Markdown horizontal line syntax reference
| You type | What renders |
|---|---|
| --- | A markdown horizontal line (thematic break) |
| *** | A markdown horizontal line made of asterisks |
| ___ | A markdown horizontal line made of underscores |
| - - - | Dashes with spaces between still form a divider |
| ---------- | More than three characters works the same |
| Title\n--- | Not a divider — renders as an H2 heading (Setext) |
How to insert a markdown horizontal line correctly
- 1
Leave a blank line above
The blank line detaches the marker from the preceding paragraph. Without it, --- under a text line redefines that line as a heading instead of drawing a markdown horizontal line.
- 2
Type three or more markers
Pick ---, ***, or ___ and repeat the character at least three times. The markdown horizontal line renders identically regardless of length, so most style guides settle on exactly three.
- 3
Follow with a blank line
A blank line after the divider keeps the next paragraph from sticking to it — and keeps the markdown horizontal line from swallowing a following dash-prefixed list into ambiguity.
- 4
Preview and copy
Use the chips above to try all three marker types, then Copy Markdown to take the exact source. The markdown horizontal line you paste renders on every CommonMark platform.
The Setext heading trap: when --- is not a horizontal line
Underneath a paragraph, a line of dashes changes meaning entirely: it becomes a Setext heading underline, promoting the text above it to an H2. So Text followed immediately by --- produces a big heading, while Text, a blank line, and --- produce a paragraph and a markdown horizontal line. This is the single most common confusion around horizontal rules, and the Title ambiguity example above shows both outcomes from a one-line difference.
The same interaction explains a subtler failure: a dash list directly above a --- can, in some renderers, attach the divider to the list. Blank lines on both sides are the fix — they terminate every surrounding construct before the markdown horizontal line starts. If a divider ever renders as something unexpected, check for missing blank lines first.
Horizontal line mistakes and their fixes
Title ---
Title ---
Without the blank line, the dashes turn Title into an H2 heading. The blank line restores the intended markdown horizontal line.
_ _ _
___
Underscores with spaces between them do not form a divider — they can even emphasize text. Keep underscore markers touching; dashes and stars may have spaces.
Two dashes --
Three dashes ---
A markdown horizontal line needs at least three marker characters. Two dashes render as literal text.
Use dividers for structure, not decoration
A markdown horizontal line signals a major section boundary — appendix, changelog split, topic change. Documents where every subsection gets a divider read as cluttered; reach for headings first and the markdown horizontal line for the few true seams.
Where the markdown horizontal line shines
Documentation reads better with honest seams. Release notes use a markdown horizontal line between versions so a reader scanning for v2.4 can jump visually from block to block; long-form guides use one before an appendix or a references section; personal notes use it to separate days or topics in a single file. Because the markdown horizontal line renders as styling rather than a character, it adapts to every theme — dark mode, print, mobile — without any extra work from the author.
Pairing the divider with headings is the classic document skeleton: an H2 announces the section, a markdown horizontal line beneath the heading block separates major movements, and white space handles everything smaller. Used this way the markdown horizontal line is doing structural work — telling the reader this is a new chapter, not a new paragraph — which is exactly the signal a divider should carry.
Frequently asked questions
Sources and spec citations
“A line consisting of optionally up to three spaces of indentation, followed by a sequence of three or more matching -, _, or * characters, each followed optionally by any number of spaces or tabs, forms a thematic break.”