Articles
Published · July 15, 2026

Markdown Horizontal Rules: Dividers for Long Notes

Three dashes, three asterisks, or three underscores on their own line make a Markdown divider. Here's the exact syntax, the two ways it silently breaks, and when a divider actually earns its place in a long note.

Quick Answer

Type three or more hyphens, asterisks, or underscores on their own line, with a blank line above and below, and you get a horizontal rule — a thin divider across the page. All three forms render identically:

---

***

___

In a long note, that line is a structural tool, not decoration. It marks a real break — a topic shift, the end of a section, the start of an appendix — the same way CommonMark's reference documents it.

How It Actually Works

Valid characters and minimum count

A horizontal rule needs three or more matching characters — hyphens (-), asterisks (*), or underscores (_) — on a line by themselves, and the characters can't be mixed within one rule: --* isn't valid, --- is. Spacing between the characters is optional and doesn't change the output, so ---, - - -, and a much longer run like ------------------------------- all render as the exact same line, per the original Markdown spec.

Indentation and precedence rules

Up to three spaces of leading indentation are allowed before the rule; four or more turns the line into an indented code block instead, per the CommonMark spec. Two ambiguity rules matter more day to day:

  • Three-or-more dashes sitting directly under a line of text, with no blank line between them, get read as a setext-style H2 underline — not a divider. The heading interpretation wins. This is the same blank-line mechanic that trips people up with Markdown line breaks more broadly: whitespace placement changes meaning.
  • A line that could be read as either a rule or a list item resolves to the rule. And a thematic break still works inside a list item, even one using a different bullet character than the list around it.

When to Use It (and When to Skip It)

A divider earns its place when it marks something structural: a shift to an unrelated topic inside one long note, the boundary before a "sources" or "appendix" block, or a clean stopping point at the end of a document. GitHub's own writing guide uses a rule this way — functionally, not decoratively — placing one right after a collapsed details block to separate it from what follows.

Two cases where a different tool fits better:

  • The break is really a new named section. If a reader would want to jump to it from a table of contents, use a heading instead — see outlining long documents with headings for when H2s beat a bare divider.
  • You're highlighting an aside, not separating sections. For a pull-quote, a warning, or a side note, reach for blockquotes and callouts instead. A rule marks a break; it doesn't add emphasis.

One habit worth keeping regardless: always put a blank line before and after the rule. It's what keeps the line from being misread as a heading underline, and it renders correctly across every CommonMark-compliant processor.

Frequently Asked Questions

What's the difference between --- and * as a horizontal rule?

Nothing rendered. CommonMark and GFM treat three-or-more hyphens, asterisks, or underscores on their own line as equivalent thematic breaks — pick one and stay consistent within a document.

Why did my --- turn into a heading instead of a divider?

If the --- sits directly under a line of text with no blank line between them, Markdown reads it as a setext-style H2 underline, not a horizontal rule. Add a blank line above the dashes to force the divider interpretation.

Can I use a horizontal rule inside a list item?

Yes. A thematic break is valid inside a list item, even one using a different bullet character than the surrounding list markers, and it won't break the list structure.

How many dashes or asterisks do I need?

Three is the minimum. Two or fewer non-space characters won't trigger a rule — CommonMark requires three or more matching characters, and you can space them out (- - -) or run them together (---) with identical results.

How Carets Fits In

Dividers matter most in one place: a single long note that keeps growing — a running log, a research doc, a scratch file with a dozen unrelated ideas stacked on top of each other. Carets is a native Markdown, plain text, and code editor for iPhone, iPad, and Mac, and it renders standard CommonMark/GFM syntax — including horizontal rules — exactly as written, so a divider you type today looks the same wherever you open the file next.

The bigger help for long notes isn't the divider itself. It's what Carets does around it: files, projects, and tags keep related notes grouped so you're not relying on dividers alone to hold one giant document together. Your files stay plain text, so nothing about how you structure a note is locked into a proprietary format.

Carets is available on the App Store for iPhone, iPad, and Mac.