Markdown cheatsheet · Horizontal rules
Horizontal rules in markdown
Three or more dashes, asterisks or underscores alone on a line become a divider. The only real catch is the blank line above it, and what happens when you forget it.
The syntax
Three or more dashes, asterisks or underscores alone on a line. All three produce exactly the same <hr>; the choice is cosmetic.
Above the line. --- Below the line.
Above the line.
Below the line.
More than three works too: ----- and *** and ___ are all the same rule. Spaces between the characters are allowed, so - - - is also valid, though there's no reason to write it that way.
The blank line is the part everyone misses
A row of dashes directly under a line of text does not make a rule. It makes that text an <h2>, because --- under text is the alternate heading syntax.
My title --- Some text.
Some text.
That's the single most common surprise with horizontal rules, and it's silent: you get a heading you didn't ask for and no error. Always leave a blank line above the rule. A blank line below is good manners but rarely required.
*** is the safer habit. Asterisks can't be confused with the heading syntax, because only --- and === mean "make the line above a heading". If you write rules often and forget blank lines, *** never bites.Which character to use
| You type | Renders as | Watch out for |
|---|---|---|
--- | Horizontal rule | Becomes an H2 if text sits directly above |
*** | Horizontal rule | Nothing. The safe choice. |
___ | Horizontal rule | Harder to read in raw text |
- - - | Horizontal rule | Valid but pointless |
Front matter uses the same characters
If your file opens with ---, that's usually not a rule. Static site generators and note apps use a pair of dash lines at the very top of a file to delimit YAML front matter, the block of metadata that never appears in the rendered output.
--- title: My post date: 2026-07-17 --- The actual content starts here.
The actual content starts here.
This only applies at the very start of the file, and only in tools that read front matter. In a plain renderer, that same block renders as a heading followed by a rule, which is exactly what you see when you paste a Jekyll post into a comment box.
What you can't do
Change the thickness or colour
There's no markdown for it. Where HTML is allowed, <hr style="border-top:2px solid red"> works, though GitHub strips the style attribute. On GitHub the rule looks the way GitHub wants it to look, full stop.
Add text in the middle of the line
Not with markdown. A centered word inside a divider needs HTML and CSS, and it won't survive most renderers. A small heading is almost always the better answer.
Make a vertical rule
No such thing. Columns need HTML or a table.
Common questions
Is <hr> the same thing?
Yes, and it works wherever inline HTML is allowed. The markdown form is shorter and always available, so prefer it.
Does a rule need blank lines on both sides?
Above: yes, always, or you may get a heading. Below: usually optional, but adding it costs nothing and keeps the raw file readable.
Why does my rule show up as a heading?
There's text on the line directly above it. Add a blank line, or switch to ***.