Horizontal rule syntax
You can use more than three characters and put spaces between them, and the line may be indented by up to three spaces. Nothing else may appear on the line, and the characters cannot be mixed: -*- is not a rule.
Text above.
---
***
___
- - -
* * * * *The setext-heading pitfall
A line of hyphens directly under a line of text is the "setext" syntax for an H2 heading, and the CommonMark spec says the heading interpretation wins. That is why a paragraph suddenly turns big and bold when you add a divider under it. Add a blank line, or use *** which never creates a heading.
This line becomes an H2 heading
---
This line stays a paragraph
---Dividers on GitHub
GitHub renders a rule as a thin grey line. H1 and H2 headings already have a bottom border on GitHub, so a rule straight under one of them looks like a double line. Also avoid --- as the very first line of a file: GitHub, Jekyll, Hugo and most static site generators read a block opened by --- at the top of a file as YAML front matter.
GitHub strips style attributes, so you cannot change the color or thickness of a divider in a README.
Styled dividers with HTML
Where raw HTML and inline styles are allowed (your own site, VS Code preview, HTML exports), an <hr> tag can be styled. On GitHub, only the plain line appears.
<hr>
<hr style="border: 0; border-top: 2px dashed #9ca3af;">When to use a divider
Use a rule for a change of topic that does not deserve a heading of its own: between a README’s badges and its body, before a footer or license note, between entries in a changelog or between letters in a single long note. If the new part has a name, a heading is better because it creates an anchor link and an entry in generated tables of contents, which a rule does not. In slide tools built on Markdown, such as Marp, a --- line separates slides.
 
---
MDTool converts Markdown to PDF, HTML and Word.
***
Released under the MIT License.Horizontal rules are not page breaks
A rule is a visual line, not a print instruction. When you convert Markdown to PDF, --- draws a line and the content continues on the same page. To force a new page, use a page break marker instead. See the page breaks guide.
Where horizontal rules work
Thematic breaks are core Markdown, so almost every renderer supports them. Chat apps are the main exception.
| Platform | Supported | Note |
|---|---|---|
| GitHub | Yes | --- at the top of a file is front matter |
| GitLab | Yes | ---, *** or ___ |
| Obsidian | Yes | --- at the top of a note starts Properties |
| VS Code preview | Yes | - |
| Notion | Yes | Typing --- creates a divider block |
| Yes | Three or more -, * or _ | |
| Discord | No | Shows the characters literally |
Frequently Asked Questions
How do I add a divider line in Markdown?
Put three hyphens (---), asterisks (***) or underscores (___) on a line by themselves, with a blank line above and below. They all render as a horizontal rule.
Should I use ---, *** or ___?
They are identical in output. --- is the most common, but *** is the safest choice directly after text because it can never be read as a setext heading underline.
Why did my text turn into a heading when I added ---?
A line of hyphens directly under text is setext heading syntax for H2. Add a blank line between the text and the --- to get a divider instead.
Does a horizontal rule create a page break in PDF?
No, it only draws a line. Use a page break marker such as <div style="page-break-after: always;"></div> on its own line to start a new page in MDTool’s Markdown to PDF converter.
Try it live
Paste this syntax into the free markdown to html converter and see the rendered output instantly. No signup, and everything runs in your browser.
Open Markdown to HTML Converter →