Supported horizontal rule forms
CommonMark recognizes three character families for thematic breaks: hyphen-minus, asterisk, and underscore. Each form needs at least three matching characters. Valid examples include `---`, `***`, `___`, `- - -`, and `* * *`. The characters must occupy a line by themselves, apart from spaces or tabs. Do not combine them in one rule, such as `*-*`, because that is not a valid thematic-break pattern. A line of three hyphens can also be interpreted as a setext heading underline when it follows paragraph text without the required separation. Add a blank line before the rule to make the intended structure clear. The rendered HTML generally contains `<hr>`.
Avoid accidental rules
Horizontal rules can appear unintentionally when a formatter or editor turns repeated punctuation into a line. Three hyphens after a paragraph may become a rule or a heading underline depending on context. A line containing fewer than three characters is not a standard horizontal rule. Asterisks used for emphasis need text around them, while asterisks alone on a line can form a rule. Underscores can also conflict with emphasis when they occur inside words or around text. Keep the rule separated from nearby paragraphs, headings, and lists. If the rule follows a list, inspect the output because indentation and blank-line handling can affect whether the parser closes the list before creating the rule.
Use thematic breaks with purpose
A horizontal rule represents a thematic break between sections or changes in subject. It should not replace a heading, provide arbitrary vertical space, or divide every short paragraph. Too many rules make a document harder to scan and can create unnecessary visual noise. Use headings when readers need named sections and use CSS for spacing when you control the page template. The `<hr>` element is meaningful in HTML, but its appearance depends on the site's stylesheet. Check color contrast, spacing, and behavior on narrow screens. If your Markdown processor adds custom styling or converts rules into another component, follow that system's documentation rather than assuming browser defaults.
How do you do it step by step?
- 1Decide whether the document needs a thematic break rather than a heading or spacing element.
- 2Place three or more matching hyphens, asterisks, or underscores on a separate line.
- 3Do not mix character types, and separate the rule from nearby blocks with blank lines.
- 4Check for heading-underline ambiguity when using three hyphens after paragraph text.
- 5Preview the generated HTML and confirm that the site's styles present the rule clearly.
Working example
This example separates two related sections without creating another heading.
`## Installation\n\nInstall the package with the documented command.\n\n---\n\n## Configuration\n\nOpen the configuration file.`
The page contains an Installation section, a thematic break, and a Configuration section. The rule normally renders as `<hr>`.
The headings still provide the document outline. The horizontal rule only signals a change between adjacent topics.
Frequently asked questions
- How many characters make a Markdown horizontal rule?
- CommonMark requires at least three matching hyphens, asterisks, or underscores. Spaces may appear between the characters, but the line must otherwise stand alone.
- Why does `---` sometimes create a heading?
- Three hyphens directly below paragraph text can act as a setext heading underline. Add a blank line before the rule when you intend a thematic break.
- Can I mix hyphens and asterisks?
- No. Use one character family per rule. Forms such as `-*-` do not meet the standard thematic-break pattern.
- Is a horizontal rule good for adding space?
- No. It communicates a thematic break. Use headings for structure and CSS or template spacing for purely visual separation.