Markdown horizontal rules and divider lines

To add a horizontal line or divider in Markdown, put three dashes (---), three asterisks (***), or three underscores (___) on a line by itself. Leave a blank line above and below it. The result is a thematic break that compiles to the HTML <hr> element.

If --- appears directly below text, some parsers treat it as a Setext heading underline. Add the blank line or use *** when that ambiguity matters.

Markdown horizontal rule syntax reference

Markdown horizontal rules key facts

• Add a horizontal rule, divider, or line by putting three or more dashes, asterisks, or underscores on their own line.
• All the marker characters on the line must be the same, so ---, ***, and ___ each work but -*- does not.
• Three characters is the minimum. A longer run such as ---------- renders the same single divider.
• Leave a blank line above and below the rule. In strict parsers like Pandoc the blank lines are required.
• A line of dashes directly under text with no blank line becomes a Setext level 2 heading, not a rule. Use *** or ___ to avoid that trap.
• All three markers compile to a single <hr> element and mark a thematic break.

Avoid the Setext-heading ambiguity

Three or more dashes can create a horizontal rule, but a line of dashes directly below text can also turn that text into a Setext H2. Add a blank line before a dash-based rule, or use *** when the surrounding content makes the intent unclear.

Use horizontal rules to mark a genuine thematic change, not between every short section. Headings provide better navigation and document structure. If a divider appears inside a list or blockquote, indentation changes which container owns it, so preview the result in the destination renderer.

Basic syntax

To create a horizontal rule, put three or more of the same marker character on a line by itself, with a blank line before and after. Dashes are the most common choice.

Markdown

Text above the rule.

---

Text below the rule.

Rendered output

HTML output

<p>Text above the rule.</p>
<hr>
<p>Text below the rule.</p>

Three characters is the minimum. Many authors use a longer run, such as ----------, purely for readability in the source. The rendered result is the same single divider.

The three marker characters

Dashes, asterisks, and underscores all produce the same horizontal rule. Choose based on readability and on avoiding conflicts with other syntax, which is covered below.

Markdown

***

- - -

___

Rendered output

HTML output

<hr>
<hr>
<hr>

Underscores (___) are supported as a horizontal rule in CommonMark, GFM, Pandoc, Markdown Extra, and MultiMarkdown. They are less common in practice because a run of underscores is harder to read in source, but they create the same thematic-break structure as dashes and asterisks.

Spacing between markers

The marker characters can be separated by spaces or tabs and still form a rule. This lets you write * * * or - - -, which some authors find easier to read.

Markdown

* * *

-  -  -

Rendered output

Blank-line requirements

A horizontal rule usually needs a blank line before it, and always benefits from a blank line after it. Without a blank line before, a run of dashes directly under a line of text is read as a Setext heading underline, not a rule.

Markdown

This is a paragraph.

---

This is the next paragraph.

Rendered output

The Setext-heading ambiguity with dashes

A line of dashes has two possible meanings. Directly under a line of text with no blank line between them, --- is a Setext heading underline, which turns the text above into a level 2 heading. With a blank line between the text and the dashes, --- is a horizontal rule. Setext heading interpretation takes precedence when both are possible.

Markdown (this is a heading, not a rule)

My section title
---

Rendered output

HTML output

<h2>My section title</h2>

Compare that with a blank line inserted, which produces a rule:

Markdown (this is a rule)

My section title

---

Rendered output

HTML output

<p>My section title</p>
<hr>

To avoid this ambiguity entirely, use asterisks or underscores for horizontal rules. *** and ___ are never mistaken for a heading underline, so they are the safest choice when a rule immediately follows text.

Flavor differences

Horizontal rules are one of the most consistent Markdown features. Three or more dashes, asterisks, or underscores form a rule in CommonMark, GFM, Pandoc, Markdown Extra, and MultiMarkdown. The Setext ambiguity with dashes exists across all of them.

The core syntax is broadly consistent. The one thing to watch is that Pandoc is strict about the surrounding blank lines, and CommonMark-compatible renderers can treat a dash line directly under text as a Setext heading rather than a rule.

Other platforms (Slack, Discord, Reddit, Notion)

Divider support in chat and note tools is uneven:

• Slack: does not render --- or *** as a horizontal rule in messages. There is no Markdown divider.
• Discord: does not render Markdown horizontal rules in messages.
• Reddit: supports --- and *** as a horizontal rule in the Markdown editor, with a blank line before the marker.
• Notion: typing --- on a new line inserts a divider block, which is Notion's own shortcut rather than rendered Markdown.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific renders a horizontal rule as a divider line separating the content above and below it. A run of dashes directly under a line of text is rendered as a level 2 Setext heading rather than a rule, following standard Markdown precedence.

Try it in the Markdific online editor.

Common mistakes and gotchas

• Dashes directly under text. --- on the line right below text with no blank line makes a Setext heading, not a rule. Add a blank line, or use ***.
• Fewer than three markers. Two dashes or asterisks do not form a rule. You need at least three.
• Mixing marker characters. -*- or --_ does not work. All the non-whitespace characters must be the same.
• Other characters on the line. A rule line can only contain the marker and spaces. Any letter or extra symbol cancels it.
• Missing blank line in strict parsers. Pandoc needs a blank line before and after the rule. Without them the rule may not render.
• Confusing a rule with an underline. Setext underlines and horizontal rules share the dash character. The blank line decides which one you get.
• Trailing content. A comment or note after the markers on the same line breaks the rule.

Best practices

• Use --- for readability in most documents, but keep a blank line above it.
• Use *** or ___ when a rule directly follows text, to avoid the Setext heading trap.
• Always leave a blank line before and after the rule for portability across parsers.
• Pick one marker style and use it consistently across a document.
• Do not rely on horizontal rules in chat tools like Slack and Discord, which do not render them.
• Use rules sparingly. They signal a real thematic break, so overusing them dilutes that meaning.

HTML equivalent

A Markdown horizontal rule compiles to a single self-closing <hr> element, regardless of which marker you used or how many characters you wrote.

Markdown

Above.

---

Below.

HTML output

<p>Above.</p>
<hr>
<p>Below.</p>

FAQ

How do you make a horizontal line in Markdown? Put three or more dashes, asterisks, or underscores on their own line, with a blank line above and below. All the characters must be the same, and the line compiles to an HTML hr element.

What is the difference between three dashes and three asterisks? Nothing in the output. ---, ***, and ___ all produce the same horizontal rule. Asterisks and underscores have the advantage of never being mistaken for a heading underline.

Should I use dashes, asterisks, or underscores for a horizontal rule? Any of the three works and renders the same divider. Use --- for readability in most documents, but switch to *** or ___ when the rule directly follows a line of text, since a run of dashes there is read as a Setext heading.

What is a thematic break in Markdown? A thematic break is the semantic name for a horizontal rule. The dashes, asterisks, or underscores compile to an HTML <hr> element, which marks a shift in topic or section rather than a visual line alone.

Why do my three dashes create a heading instead of a line? A line of dashes directly under text with no blank line between them is a Setext heading underline, which makes the text above a level 2 heading. Add a blank line before the dashes, or use asterisks, to get a rule.

Do underscores work as a horizontal rule in Markdown? Yes. Three or more underscores (___) form a horizontal rule in CommonMark, GFM, Pandoc, Markdown Extra, and MultiMarkdown, exactly like dashes and asterisks. They are just less common in source because they are harder to read.

How many characters do you need for a horizontal rule? At least three of the same marker. You can use more for readability, but the rendered rule is identical.

Can you put spaces between the markers? Yes. * * * and - - - both work. The line only needs three or more of the same non-whitespace character, and spaces between them are ignored.

Do horizontal rules work in Slack and Discord? No. Neither Slack nor Discord renders Markdown horizontal rules in messages. Reddit and Notion do support a divider, though Notion uses its own shortcut.

What HTML does a Markdown horizontal rule produce? It produces a single hr element. The marker character and the number of characters do not change the output.

Sources and compatibility references

• CommonMark 0.31.2: thematic breaks
• CommonMark 0.31.2: Setext headings

Use these primary references for syntax rules. Renderer behaviour can still vary by version and configuration, so preview important documents in their final destination.

Related pages

• Markdown documentation hub
• Headings in Markdown
• Paragraphs in Markdown
• Line breaks in Markdown
• Escaping characters
• Markdown flavors compared