Three or more dashes on a line of their own draw a horizontal rule. It is the simplest element in Markdown and it hides the format’s single nastiest surprise: put those dashes directly under a paragraph and you do not get a divider, you get a heading.
Some text above.
---
Some text below.
***
___
This paragraph is followed by dashes
---Some text above.
Some text below.
This paragraph is followed by dashes
Look at the last one in the preview. The dashes turned the line above into an <h2>.
The three markers
Dashes, asterisks or underscores — three or more, on their own line:
---
***
___All three produce the same <hr>. Spaces between the characters are allowed, so - - - works too, though there is no reason to write it that way.
--- is the conventional choice, and the one every editor inserts.
The blank-line trap
This is the whole reason this page exists:
A paragraph.
---A paragraph.
A line of dashes immediately below a paragraph is Setext heading syntax — the old style where you underline a heading instead of prefixing it. = makes an <h1>, - makes an <h2>. See headings.
The fix is one blank line:
A paragraph.
---A paragraph.
If a divider in your document keeps turning into a heading, this is why. Asterisks have no such ambiguity, which is the one argument for ***.
Front matter uses the same characters
Static site generators put metadata at the top of a file between two lines of dashes:
---
title: My post
date: 2026-08-16
---
The content starts here.title: My post date: 2026-08-16
The content starts here.
That block is not Markdown at all — it is YAML, handled by the tool before the Markdown parser ever sees the file. It only counts as front matter when it is the very first thing in the document. A --- further down is an ordinary rule.
Every guide on this site starts with exactly such a block.
When to use one
Sparingly. A horizontal rule is a strong visual break, and headings usually express structure better. The cases where a rule genuinely earns its place:
- separating the body of a document from footnotes or an appendix
- marking a scene change in prose, where a heading would be wrong
- splitting slides, in tools that turn Markdown into a presentation — many use
---as the page break
Common mistakes
No blank line above. You get an <h2> instead of a rule. The most common Markdown surprise after line breaks.
Fewer than three characters. -- is nothing; --- is a rule.
Mixing characters. -*- does not work. All three must be the same.
Using a rule instead of a heading. If the sections need names, give them headings. A rule tells the reader something changed but not what.
Expecting to style it. Markdown has no syntax for thickness, colour or width. That is CSS.
FAQ
How do I add a horizontal line in Markdown?
Put three or more dashes, asterisks or underscores on a line of their own, with a blank line above them: ---.
Why do my dashes turn into a heading?
Because a line of dashes directly beneath a paragraph is the old Setext syntax for an <h2>, which underlines a heading rather than prefixing it. Leave a blank line between the paragraph and the dashes and you get a rule instead.
What is the difference between ---, *** and ___?
None in the output — all three render the same horizontal rule. --- is conventional; *** has the advantage of never being mistaken for a Setext heading.
What is the --- block at the top of a Markdown file?
Front matter: a block of YAML metadata — title, date, tags — that the site generator reads and removes before rendering. It only counts as front matter at the very top of the file.
Can I change the style of a horizontal rule in Markdown?
No. Markdown describes the content, and how the rule looks is a stylesheet decision. Target the hr element in your CSS.