Learn how to create horizontal rules in Markdown using hyphens, asterisks, and underscores.
This guide explains the correct syntax, practical examples, GitHub compatibility, best practices, common mistakes, and FAQs.
A Markdown horizontal rule is a visual divider that separates sections of content. It helps organize long documents by creating a clear break between topics and is widely supported across GitHub, VS Code, Obsidian, and other Markdown editors.
Practice as you read: Open the Markdown Editor to create horizontal rules with live preview, or keep the Markdown Cheat Sheet open for quick syntax lookup.
A Markdown horizontal rule is a visual divider that separates sections of content. It helps organize long documents by creating a clear break between topics.
Horizontal rules improve readability and make documentation easier to scan, especially in:
Instead of using blank lines or repeated characters, Markdown provides a dedicated syntax for creating section dividers.
As documentation grows, readers need visual cues to identify where one section ends and another begins.
Horizontal rules help you:
Well-placed horizontal rules create a cleaner reading experience without adding unnecessary complexity.
Markdown supports three different ways to create a horizontal rule.
All of the following produce the same result.
---
Output
Rendered Output
Hyphens are the most commonly used option and are recommended for consistency.
***
Output
Rendered Output
___
Output
Rendered Output
Although all three styles are valid, most documentation projects choose one style and use it consistently.
A horizontal rule requires at least three matching characters.
These are valid:
---
***
___
These are not valid:
--
**
__
Using fewer than three matching characters will not create a horizontal rule.
# Introduction
Content goes here.
---
# Installation
Installation instructions.
Output
Rendered Output
Content goes here.
Installation instructions.
This is one of the most common layouts used in GitHub README files.
Horizontal rules work best when separating major sections such as:
Avoid placing horizontal rules between every paragraph, as excessive use can make documents feel cluttered.
One of the most common uses of horizontal rules is separating major headings.
# Introduction
Welcome to the guide.
---
# Installation
Follow these installation steps.
---
# Usage
Learn how to use the project.
Output
Rendered Output
Welcome to the guide.
Follow these installation steps.
Learn how to use the project.
This layout is widely used in GitHub README files and technical documentation because it clearly separates major sections.
Horizontal rules can separate different lists or groups of information.
## Frontend
- HTML
- CSS
- JavaScript
---
## Backend
- Node.js
- Express
- MongoDB
Output
Rendered Output
This approach makes long documentation easier to scan.
Horizontal rules help distinguish different code blocks.
```bash
npm install
```
---
```bash
npm run dev
```
Output
Rendered Output
npm install
npm run dev
Separating examples improves readability, especially in tutorials and API documentation.
| Name | Role |
|------|------|
| John | Admin |
| Sarah | Editor |
---
| Product | Price |
|---------|------:|
| Laptop | $999 |
| Mouse | $29 |
Horizontal rules make it easy to distinguish between multiple tables in the same document.
---
Using dividers between screenshots creates a cleaner visual layout in documentation and tutorials. See Markdown Images for image syntax details.
> **Important**
>
> Always create a backup before updating.
---
> **Tip**
>
> Test your changes locally before deploying.
Output
Rendered Output
Important
Always create a backup before updating.
Tip
Test your changes locally before deploying.
Combining blockquotes with horizontal rules makes notes and tips stand out without cluttering the page.
GitHub fully supports all three Markdown horizontal rule syntaxes:
---***___Most GitHub repositories prefer using three hyphens (---) because they are easy to read and commonly used throughout documentation.
Horizontal rules work in:
For consistency, use the same style across your entire repository.
| Platform | Horizontal Rules Supported |
|---|---|
| GitHub | ✅ |
| GitLab | ✅ |
| VS Code Preview | ✅ |
| Obsidian | ✅ |
| Notion | ✅ |
| Stack Overflow | ✅ |
| Docusaurus | ✅ |
| MkDocs | ✅ |
| Hugo | ✅ |
| Astro Starlight | ✅ |
Horizontal rules are part of the CommonMark specification, making them one of the most widely supported Markdown features across editors and documentation platforms.
Using horizontal rules consistently makes Markdown documents easier to read and navigate. Follow these best practices when adding section dividers.
Horizontal rules are intended to separate large sections of content rather than individual paragraphs.
Good example:
# Installation
Installation instructions...
---
# Usage
Usage examples...
Avoid inserting a divider after every paragraph, as it can make the page feel cluttered.
Markdown supports three valid syntaxes:
---
***
___
Although all three produce the same result, it's best to choose one style and use it consistently throughout your documentation.
For most projects, three hyphens (---) are the recommended choice.
For better compatibility, leave one blank line before and after each horizontal rule.
Good example:
First section.
---
Second section.
This improves readability and ensures consistent rendering across Markdown editors.
Horizontal rules separate content—they do not replace headings.
Instead of writing:
Introduction
---
Installation
Use proper headings:
# Introduction
Content...
---
# Installation
Content...
This creates a better document structure and improves accessibility.
Always preview your Markdown document to verify that horizontal rules render correctly.
Most editors, including GitHub, VS Code, Obsidian, and Markdown preview tools, display horizontal rules consistently. Preview in the Markdown Editor before publishing.
Even though horizontal rules are simple, a few common mistakes can prevent them from rendering correctly.
Incorrect:
--
Correct:
---
A horizontal rule requires at least three matching characters.
Incorrect:
-*-
Correct:
---
or
***
or
___
Always use the same character throughout the entire rule.
Although some Markdown parsers accept it, placing blank lines around horizontal rules improves compatibility and readability.
Recommended:
Paragraph one.
---
Paragraph two.
Remember that headings organize document structure, while horizontal rules simply divide sections.
Use both together for the best reading experience.
Horizontal rules are commonly used in documentation projects.
# Project Name
Project description.
---
## Installation
Installation steps.
---
## Usage
Usage examples.
---
## License
MIT
# API Documentation
Authentication details.
---
# Endpoints
List of API endpoints.
---
# Error Codes
Common API responses.
# Step 1
Prepare your environment.
---
# Step 2
Install dependencies.
---
# Step 3
Run the application.
These layouts are widely used in GitHub repositories, documentation websites, and developer blogs because they create a clear visual separation between major sections.
The easiest way to understand horizontal rules is to experiment with them.
Open the Markdown Editor and try creating dividers using hyphens, asterisks, and underscores. Preview the rendered output instantly and compare how different Markdown elements work together.
You can also export your Markdown as HTML, PDF, or other supported formats using the Markdown to HTML and Markdown to PDF conversion tools.
Markdown horizontal rules are a simple but powerful way to organize documentation and improve readability.
In this guide, you learned:
Whether you're writing a GitHub README, technical documentation, tutorials, or knowledge base articles, horizontal rules help readers navigate long documents more easily and create a cleaner, more professional layout.
Continue learning Markdown with these guides:
Available now
The best way to learn horizontal rules is by writing them yourself. Open the Markdown Editor to experiment with dividers, headings, lists, and blockquotes while previewing the rendered output in real time.
A horizontal rule is a visual divider that separates sections of content in a Markdown document. It improves readability by creating a clear break between topics.
Use three or more matching characters on a separate line. Example: ---. You can also use *** or ___. All three produce the same horizontal line.
Although Markdown supports hyphens (---), asterisks (***), and underscores (___), most developers and documentation projects use three hyphens (---) because they are easy to read and widely adopted.
Yes. GitHub Flavored Markdown fully supports horizontal rules created with ---, ***, and ___. They work in README files, Wikis, Issues, Discussions, Pull Requests, and GitHub Pages.
Yes. For example, ------ is also valid. However, using exactly three characters keeps your Markdown cleaner and more consistent.
A line break moves text to the next line. A horizontal rule creates a visible divider between two sections of content. They serve completely different purposes.
The most common causes are using fewer than three matching characters, mixing different characters (for example -*-), placing other text on the same line, or incorrect spacing. Always place the horizontal rule on its own line.
Yes. Most Markdown editors support horizontal rules inside lists and blockquotes, although indentation must be correct for consistent rendering.
Yes. Horizontal rules are part of the CommonMark specification and are supported by GitHub, GitLab, VS Code, Obsidian, Notion, Stack Overflow, Docusaurus, MkDocs, Hugo, Astro Starlight, and nearly every modern Markdown editor.
No. Horizontal rules should separate major sections only. Overusing them can make documentation harder to read and reduce their visual impact.