Markdown Horizontal Rules: Thematic Breaks Guide

---
***
___

Thematic breaks—traditionally called horizontal rules or dividing lines—provide visual separation between distinct topics, chapters, conversational scene shifts, or document sections.

In CommonMark and Oyma, horizontal rules compile to the semantic HTML <hr> element, rendering a subtle, elegant hairline divider across the page.

Horizontal rule syntax

In CommonMark, a thematic break is created by placing three or more hyphens (-), asterisks (*), or underscores (_) on a line by themselves:

---
***
___

All three variations produce identical semantic <hr> elements.

Whitespace within thematic breaks

CommonMark also permits spaces between the break characters:

- - -
* * *
_ _ _

Best practice: Use --- with blank line buffers

While asterisks and underscores are valid, using three hyphens (---) surrounded by empty blank lines is the universal standard:

End of Chapter 1 discussion on cryptographic architecture.

---

Chapter 2 begins here with threat model definitions.

Critical pitfall: Setext heading collisions

The most common mistake when writing horizontal rules is omitting the blank line preceding the hyphens:

<!-- INCORRECT: Produces an H2 heading, NOT a divider! -->
Summary of key decisions
---

<!-- CORRECT: Produces a heading followed by a divider -->
## Summary of key decisions

---

When three hyphens appear immediately beneath a line of text without a separating blank line, CommonMark treats the hyphens as a Setext H2 heading underline. Always ensure an empty line precedes your divider.

Frontmatter vs horizontal rules

Markdown documents often start with YAML frontmatter bounded by triple hyphens:

---
title: "Document Title"
updated: 2026-10-09
---

# Document Title

This is the document introduction.

---

This is the next section following a thematic divider.

• Top of file: The first --- pair wraps YAML metadata processed by site engines and note vaults.
• Body of file: Subsequent --- blocks surrounded by blank lines are rendered as visual dividing rules.

Thematic dividers in Oyma

In Oyma on macOS:

• Typing --- on a blank line and pressing Return instantly instantiates a hairline separator styled with native macOS border tokens.
• The divider responds dynamically to appearance changes between Light and Dark mode, using subtle system border tokens (var(--color-border-subtle)) rather than harsh solid black or gray lines.
• In live-preview mode, the separator appears as a clean typographic rule, but your cursor can always move across it to inspect or edit the raw triple hyphens.
• Raw files on disk remain strictly standard CommonMark plain text, ready for any markdown parser or version control system.

HTML compilation and screen reader accessibility

In the CommonMark parsing pipeline, horizontal rule tokens compile to the semantic HTML <hr> element:

<hr class="divider" role="separator" />

From an accessibility (a11y) standpoint, modern assistive technologies like Apple VoiceOver announce <hr> elements as “separator” or “thematic break”. This provides screen reader users with structural context when shifting between distinct concepts, meeting WCAG 2.2 guidelines for document structure.

Printing and PDF export: Automatic page breaks

When exporting meeting notes, technical specifications, or executive summaries from Oyma to PDF or hardcopy print, horizontal rules can optionally function as explicit page breaks using standard print CSS:

@media print {
  hr.page-break {
    page-break-after: always;
    break-after: page;
    visibility: hidden;
    height: 0;
    margin: 0;
  }
}

This dual utility allows you to organize long multi-topic meeting transcripts into cleanly divided printed documents without leaving awkward orphaned headers at the bottom of printed pages.

Frequently asked questions

What is the recommended syntax for a Markdown horizontal rule?

Three hyphens (`---`) on a dedicated line surrounded by blank lines is the most common standard. It compiles cleanly to the HTML `

---

` thematic break element.

Why should I surround horizontal rules with blank lines?

If three hyphens (`---`) appear immediately below a line of text without an intervening blank line, CommonMark parses the hyphens as a Setext H2 heading underline rather than a horizontal divider.

How is a horizontal rule different from YAML frontmatter?

YAML frontmatter begins on line 1 of the file between two sets of triple hyphens (`---`). A horizontal rule occurs inside the body of the document and is rendered as a visual dividing line.

Can spaces be placed between the characters of a horizontal rule?

Yes. CommonMark allows spaces between the characters of a horizontal break: `- - -`, `* * *`, or `_ _ _` are all valid thematic breaks.