Markdown Horizontal Line
Three ways to draw a horizontal line (also called a horizontal rule or divider) in Markdown: ---, ***, and ___. With live examples, the mistake that turns your line into a heading, and what works in Discord, Slack, and Notion.
Short answer
Put three hyphens on a line by themselves, with a blank line above: ---. Three asterisks *** or underscores ___ work the same way, and all three render as an <hr> line. Without the blank line, --- turns the text above it into a heading.
Basic Syntax
Put three or more identical characters on their own line. All three produce the exact same <hr> HTML output. Blank lines around the rule keep it safe in every renderer.
Markdown
Above the line
---
Below the linePreview
Above the line
Below the line
Markdown
Above the line
***
Below the linePreview
Above the line
Below the line
Markdown
Above the line
___
Below the linePreview
Above the line
Below the line
Variations That Also Work
The CommonMark rules: at least three of the same character, optional spaces or tabs between them, up to three spaces of indentation, and nothing else on the line. A rule made of *** or ___ can even sit directly between two paragraphs.
Markdown
Above
- - -
BelowPreview
Above
Below
Markdown
Above
----------
BelowPreview
Above
Below
Markdown
Above
* * * * *
BelowPreview
Above
Below
Markdown
A paragraph right above
***
A paragraph right belowPreview
A paragraph right above
A paragraph right below
Common Mistakes
The most common issue: writing --- directly under a line of text. That is the underline form of an H2 setext heading, so the text becomes a heading instead of getting a divider.
Markdown
Paragraph text
---
This looks like a horizontal line but the text above is now an H2.Preview
Paragraph text
This looks like a horizontal line but the text above is now an H2.
Markdown
Paragraph text
---
This is a horizontal line.Preview
Paragraph text
This is a horizontal line.
Markdown
--
Not a horizontal line: it needs at least 3 characters.Preview
--
Not a horizontal line: it needs at least 3 characters.
Markdown
---
Four spaces of indentation make a code block.Preview
---
Four spaces of indentation make a code block.
Markdown
-*-
--_Preview
-*-
--_
--- at the Top of a File
When --- is the very first line of a file, GitHub, Jekyll, Hugo, Obsidian, and most static-site generators read it as the start of a YAML front matter block, not a horizontal line. Everything up to the next --- is treated as metadata.
---
title: My Project
tags: [docs]
---
# My ProjectIf you want a visible line at the top of a file, use *** or put a heading above it.
Quick Reference
| Syntax | Valid? | Notes |
|---|---|---|
| --- | Yes | Most common: three hyphens |
| *** | Yes | Three asterisks |
| ___ | Yes | Three underscores |
| - - - | Yes | Spaces between characters allowed |
| ------ | Yes | More than 3 characters is fine |
| --- | Yes | Up to 3 spaces of indentation |
| <hr> | Yes | Raw HTML, where the renderer allows it |
| -- | No | Minimum is 3 characters |
| -*- | No | Cannot mix character types |
| --- | No | 4 spaces of indentation = code block |
| Paragraph\n--- | No | No blank line = setext H2 heading, not a rule |
Platform Support
Horizontal lines work in every document renderer. Chat apps are the exception: Discord has no divider syntax, and Slack only draws one inside an app's markdown block. See the Discord and Slack guides for what those apps do support.
| Platform | Supports ---? | Notes |
|---|---|---|
| GitHub | Yes | All three variants. A --- on the first line of a file starts YAML front matter instead. |
| GitLab | Yes | All three variants. |
| VS Code preview | Yes | All three variants. |
| Obsidian | Yes | All three, with or without spaces between the characters. A --- on line 1 starts the Properties block. |
| Notion | Yes | Typing --- creates a divider block. Pasted rules convert too. |
| Yes | In the Markdown editor and on old.reddit.com. The Rich Text editor has no divider. | |
| Slack | Partial | Not in the message composer or in mrkdwn. An app's Block Kit markdown block renders --- as a divider, and Block Kit has a divider block. |
| Discord | No | ---, *** and ___ stay as literal characters. Paste a line of box-drawing characters (─) instead. |
| CommonMark / GFM | Yes | Called a thematic break. Renders as <hr>. |
Frequently Asked Questions
How do I add a horizontal line in Markdown?
Put three or more hyphens (---), asterisks (***), or underscores (___) on a line by themselves. All three render as an <hr> horizontal line. Leave a blank line above ---, or the text above it becomes a heading.
Why is my --- creating a heading instead of a line?
A --- line directly under a line of text is a setext heading underline, so the text above becomes an H2. Add a blank line between the text and the ---, or use *** or ___, which never make headings.
What is the difference between ---, ***, and ___?
None in the output. All three produce the same <hr> element. The only difference is that --- right under a paragraph turns the paragraph into a heading, while *** and ___ always make a line. Most style guides use ---.
Is a horizontal rule the same as a horizontal line, divider, or thematic break?
Yes. They are four names for the same thing. The original Markdown docs call it a horizontal rule, the CommonMark spec calls it a thematic break, HTML calls it <hr>, and apps like Notion call it a divider.
What is the minimum number of characters for a horizontal rule?
Three. You can use more (------), put spaces or tabs between them (- - -), and indent the line up to three spaces. Four spaces of indentation turns it into a code block. Nothing else can be on the line.
Can I mix hyphens, asterisks, and underscores on one line?
No. Every character must be the same. A line like -*- or --_ is not a horizontal rule and renders as plain text.
Does a horizontal line work on GitHub, Discord, Slack, and Notion?
GitHub, GitLab, Obsidian, VS Code, and Reddit's Markdown editor render all three forms. In Notion, typing --- creates a divider block. Slack only renders --- inside an app's markdown block, not in normal messages. Discord has no horizontal rule at all.
How do I make a horizontal line in Discord?
Discord has no horizontal rule syntax, so --- stays as three dashes. The common workaround is to paste a row of Unicode box-drawing characters, such as ──────────, which reads as a line. Keep it short so it does not wrap on mobile.
Why does --- at the top of my file disappear?
A --- on the very first line opens a YAML front matter block in GitHub, Jekyll, Hugo, Obsidian, and most static-site generators, so it is treated as metadata, not a line. Put some content above it, or use *** for a rule at the top of the file.
What HTML does a Markdown horizontal rule produce?
An <hr> element. You can also write <hr> directly where raw HTML is allowed (GitHub, Obsidian, VS Code). The line's color and thickness come from the site's CSS; Markdown has no syntax to change them, and GitHub strips style attributes.