Markdown Horizontal Rule — Dividers with ---, ***, and ___

Three Ways to Create a Horizontal Rule

A horizontal rule is a visual divider between sections of a document. In Markdown, you create one by putting three or more hyphens, asterisks, or underscores on a line by itself. All three produce the same <hr> element.

Hyphens: ---

Above the line

---

Below the line

Asterisks: ***

Above the line

***

Below the line

Underscores: ___

Above the line

___

Below the line

All three render identically. Pick one style and stick with it across your documents — --- is the most common choice.

Variations That Work

You are not limited to exactly three characters. Markdown accepts three or more, and it also allows spaces between them. These all render the same horizontal rule.

- - -

* * *

--------

Longer lines are handy when you want the raw Markdown to stand out visually in a plain-text editor. The rendered output is always the same single line.

When to Use Horizontal Rules

A horizontal rule works best as a light visual break. Common uses include:

• Separating sections in a long document where a heading would be too heavy
• Before footnotes or a closing note, to set it apart from the main text
• Between major topic changes within the same section
• In README files to divide the intro, installation, usage, and license areas

# My Project

A short description of what this project does.

---

## Installation

Run the installer and follow the prompts.

---

Released under the MIT License.

Horizontal Rules vs Headings

Rules and headings solve different problems. A horizontal rule is purely visual: it draws a line and carries no meaning. A heading creates document structure: it gives a section a title, shows up in tables of contents, and helps screen readers and search engines understand your content.

A good rule of thumb: if you would want the section in a table of contents, use a heading. If you just want to pause between two ideas, use a rule. You can also combine them — a rule above a heading is a common way to make major sections stand out.

The Heading/Rule Ambiguity

This is the most common surprise with horizontal rules. If --- sits directly below a line of text, Markdown does not draw a line. It turns the text above into a level-2 heading (a “Setext” heading).

This was meant to be a paragraph
---

The text became an H2 heading, and no horizontal rule was created. The fix is simple: add a blank line before ---.

This is a paragraph

---

The next paragraph

Only hyphens (and equals signs for H1) trigger this behavior. *** and ___ never create headings, so they are a safe choice if you often forget the blank line. As a habit, always put a blank line above and below your rule.

Common Mistakes

Forgetting the blank line before ---

As shown above, --- directly under text creates an H2 heading instead of a line. Always leave an empty line between the text and the rule.

Using only two characters

A horizontal rule needs at least three characters. Two hyphens are not enough — they render as literal text.

---    <-- works, renders a line
--     <-- too short, renders as text

Confusing --- with YAML front matter

Many Markdown tools use --- at the very top of a file to mark the start and end of YAML front matter (metadata such as title, date, and tags). That block is not a horizontal rule, and it is not rendered as one. If you want a divider near the top of a document, put it after the front matter block and keep a blank line around it.

---
title: My Document
date: 2026-10-13
---

# My Document

Intro text.

---

First section.

Platform Support

All three horizontal rule syntaxes (---, ***, and ___) are part of the original Markdown specification and the CommonMark standard. They work on every major platform that renders Markdown files: GitHub, GitLab, Bitbucket, VS Code, Obsidian, Bear, iA Writer, Typora, and MDViewer. If a tool renders Markdown at all, it renders horizontal rules. How the line looks — thickness, color, spacing — depends on the stylesheet of each app.

FAQ

How do I add a horizontal line in Markdown?

Put three or more hyphens, asterisks, or underscores on a line by itself: ---, ***, or ___. Leave a blank line above and below. The result is an <hr> element, a thin line across the page.

What is the difference between ---, ***, and ___ in Markdown?

There is no difference in the rendered result — all three create the same <hr>. The one practical difference is that --- directly under a line of text turns that text into a heading, while *** and ___ never do. Choose one style and use it consistently.

Why does my --- create a heading instead of a line?

Because it sits directly below a line of text. Markdown reads --- under text as a Setext heading underline and makes the text an H2. Add a blank line between the text and ---, or switch to *** or ___.

Preview Your Markdown with MDViewer

MDViewer is a native macOS app for reading and previewing Markdown files. Double-click any .md file in Finder and see it rendered instantly — horizontal rules, headings, tables, code blocks, and more. Lite is free; Pro adds editing, Git history, and PDF export.

Requires macOS 13.0 or later. Intel and Apple Silicon.