Markdown Horizontal Rules

A horizontal rule creates a visual break between major sections of a Markdown document. It's commonly used to separate topics in README files, documentation, tutorials, changelogs, and long-form articles.

Markdown supports three equivalent syntaxes.

Using Hyphens (Recommended)#

---

Using Asterisks#

***

Using Underscores#

___

All three produce the same horizontal divider. Most projects choose one style and use it consistently throughout the document. Three hyphens (---) are the most common choice in GitHub repositories and technical documentation.

💡 Pro Tip: Consistency matters more than the character you choose. Switching between ---, ***, and ___ throughout the same document makes large documentation projects harder to maintain.

A horizontal rule requires at least three matching characters.

These are valid

---

***

___

These are also valid

- - -

* * *

_ _ _

The spaces are optional as long as all characters match.

These are not valid

--

**

__

Using fewer than three matching characters won't create a horizontal rule.

Horizontal rules work best when one section is complete and the next begins.

Common examples include separating:

• Introduction and Installation
• Installation and Usage
• Features and Configuration
• Tutorials and Examples
• API Reference sections
• FAQ and License
• Multiple code examples or screenshots

Avoid inserting a divider after every paragraph. Too many horizontal rules make a document harder to scan instead of easier to read.

💡 Workflow Tip: Use headings to organize document structure and horizontal rules to separate major sections. The two work together—they don't replace each other. See Markdown Headings for heading hierarchy.

Horizontal rules work with other Markdown elements to separate related content without changing the document structure. They're most effective between major sections, not between individual paragraphs.

Between Headings#

One of the most common patterns is placing a horizontal rule between major sections of a document.

Example

# Introduction

Project overview.

---

# Installation

Setup instructions.

---

# Usage

Examples and commands.

This layout is widely used in GitHub README files, technical documentation, and user guides because each section is clearly separated without adding visual clutter.

Between Lists#

Horizontal rules can separate different groups of related items.

Example

## Frontend

- HTML
- CSS
- JavaScript

---

## Backend

- Node.js
- Express
- PostgreSQL

This pattern works well for feature lists, checklists, technology stacks, and documentation with multiple categories.

Between Code Blocks#

When showing multiple code examples, a horizontal rule makes it easier to distinguish one example from the next.

Example

```bash
npm install
```

---

```bash
npm run dev
```

For code syntax, language identifiers, and fenced blocks, see the Markdown Code Blocks guide.

Between Tables#

Large documentation often contains multiple tables. A horizontal rule creates a clear separation before the next dataset.

Example

| Name | Role |
|------|------|
| John | Admin |

---

| Product | Price |
|---------|------:|
| Laptop | $999 |

This approach keeps comparison tables from running together.

Between Images#

Horizontal rules help separate screenshots, diagrams, or product images in long tutorials.

Example

![Homepage](homepage.png)

---

![Dashboard](dashboard.png)

For image syntax, captions, and relative paths, see the Markdown Images guide.

Between Blockquotes#

Documentation often places notes, warnings, or tips between larger sections. A horizontal rule helps distinguish separate callouts.

Example

> **Important**
>
> Back up your project before upgrading.

---

> **Tip**
>
> Test changes locally before deploying.

This pattern is common in setup guides and deployment documentation.

💡 Pro Tip: A horizontal rule separates related sections. If you're only trying to create extra spacing, use normal paragraph breaks instead of adding unnecessary dividers.

Horizontal rules are part of the CommonMark specification, so they're supported by nearly every modern Markdown editor and documentation platform.

GitHub Flavored Markdown (GFM) supports all three standard syntaxes:

---

***

___

You'll see horizontal rules rendered correctly in:

• README files
• Wikis
• Issues
• Pull Requests
• Discussions
• GitHub Pages

Although all three styles are valid, most open-source projects standardize on --- for consistency.

💡 Workflow Tip: If you're contributing to an existing project, follow the divider style already used in the repository instead of introducing a different one.

Horizontal rules are one of the most widely supported Markdown features because they're part of the CommonMark specification. Most editors and documentation frameworks render them consistently.

Since horizontal rules are a core Markdown feature, rendering differences between platforms are uncommon.

A few simple habits keep Markdown documents clean and consistent.

Choose One Divider Style#

Markdown supports ---, ***, and ___, but it's better to use a single style throughout the document.

For most projects, three hyphens (---) are the easiest to read and the most commonly used.

Leave Blank Lines Around Horizontal Rules#

Place a blank line before and after every horizontal rule.

Recommended

First section.

---

Second section.

This improves readability and avoids parser inconsistencies in some Markdown editors.

Don't Confuse Horizontal Rules with Setext Headings#

This is one of the most common Markdown mistakes.

The following is not a horizontal rule:

Installation
---

Most CommonMark parsers interpret this as a Setext heading (H2) rather than a section divider.

If your goal is a horizontal rule, leave a blank line before it.

Correct

Installation

---

Next section starts here.

💡 Pro Tip: If --- appears immediately below a line of text, check whether your Markdown parser is creating a heading instead of a divider.

Use Horizontal Rules Between Major Sections#

Horizontal rules separate topics—not individual paragraphs.

Good examples include:

• Introduction → Installation
• Installation → Usage
• Usage → Examples
• API → FAQ
• FAQ → License

Using a divider every few paragraphs usually makes documentation harder to scan.

Use Headings and Horizontal Rules Together#

Headings define the document structure. Horizontal rules improve visual separation. Neither replaces the other.

Preview Before Publishing#

Before publishing, preview the document in your Markdown editor to verify that headings, lists, tables, and horizontal rules render as expected.

If you're exporting your document, it's also worth checking the output in the Markdown to HTML or Markdown to PDF tool.

Most rendering issues come from small formatting mistakes rather than the horizontal rule itself.

Using Fewer Than Three Characters#

A horizontal rule requires at least three matching characters.

Incorrect

--

Correct

---

Mixing Different Characters#

Only one character type should be used.

Incorrect

-*-

Correct

---

***

___

Confusing YAML Front Matter with Horizontal Rules#

Many static site generators use --- to define front matter.

Example

---
title: Markdown Guide
description: Learn Markdown.
---

This is metadata, not a horizontal rule.

Frameworks such as Hugo, Jekyll, Astro, and Docusaurus treat this block differently from normal Markdown content.

Replacing Structure with Dividers#

A horizontal rule doesn't create document structure.

Always use proper headings (#, ##, ###) and use horizontal rules only when you want a clear visual break between major sections.

Using Too Many Dividers#

Adding a horizontal rule after every paragraph reduces their visual impact.

If readers see a divider every few lines, the document becomes more difficult—not easier—to scan.

💡 Workflow Tip: Think of horizontal rules as chapter breaks rather than paragraph separators. They work best when used sparingly.