How to Add a Horizontal Line in Markdown

A horizontal line in markdown is one of the simplest yet most useful formatting tools available. It creates a visual divider between sections of content, making your documents easier to scan and more organized. Whether you are writing documentation, a README file, or a blog post, knowing how to use markdown for horizontal line dividers will improve the structure of your writing.

This guide explains every method and covers platform-specific behavior so you can use horizontal lines confidently anywhere. Read our markdown cheatsheet for more.

What Is a Horizontal Line in Markdown?

A horizontal line, also called a horizontal rule or thematic break, renders as a thin line stretching across the full width of your content area. In HTML, it translates to an <hr> tag. Writers use it to separate topics, signal a shift in tone, or break up long documents into digestible sections.

Three Ways to Add a Horizontal Line in Markdown

Markdown gives you three syntax options that all produce the same result. Each one requires three or more consecutive characters on their own line with no other content.

Hyphens

---

Three hyphens are the most popular choice. They are quick to type and visually clean in raw markdown files.

Asterisks

***

Three asterisks work identically. Some writers prefer them because there is no risk of accidentally creating a heading, which can happen with hyphens if text appears on the line directly above.

Underscores

___

Three underscores are the third option. They are less commonly used but fully supported across all standard markdown parsers.

You can also use more than three characters if you prefer a more visible divider in your raw text:

----------

This renders exactly the same way as three hyphens.

A Common Mistake When You Add Horizontal Line Markdown

One of the most frequent errors is placing three hyphens directly below a line of text without a blank line in between. When you do this, most parsers interpret the text above as a heading rather than a paragraph followed by a horizontal line.

For example, this creates a heading instead of a divider:

Some text
---

To avoid this, always leave a blank line before your horizontal rule:

Some text

---

This ensures the parser treats them as two separate elements.

GitHub Markdown Horizontal Line

If you work with GitHub, you will encounter horizontal lines frequently in README files, pull request descriptions, and wiki pages. All three syntax options work in GitHub markdown. Horizontal line usage in GitHub markdown follows the CommonMark specification, so the behavior is predictable and consistent.

A typical use case in a GitHub README might look like this:

## Features

List of features here.

---

## Installation

Installation steps here.

The horizontal line in GitHub markdown provides a clean visual break between major sections without relying solely on headings.

Discord Markdown Horizontal Line

Discord supports a limited subset of markdown in chat messages, but horizontal lines are not one of the supported features. If you try typing --- or *** in a Discord message, the app will not render a horizontal rule. Instead, it may display the characters as plain text or interpret the asterisks as bold/italic formatting.

To work around the lack of a Discord markdown horizontal line, many users create visual dividers using repeated characters or emoji:

─────────────────

This is not true markdown, but it serves the same visual purpose in Discord conversations.

When to Use a Horizontal Line in Markdown

Horizontal lines work best in specific situations. Use them to separate a document header or metadata block from the main content, to divide unrelated sections within a single document, or to mark a transition in narrative or topic. They are also helpful in long README files where multiple major sections benefit from strong visual boundaries.

Avoid overusing them. If every section of your document is separated by a horizontal line, the effect loses its impact and the document can feel choppy. Headings alone are usually sufficient for most structural needs, with horizontal lines reserved for more significant breaks.

Horizontal Lines and Front Matter

If you use static site generators like Jekyll, Hugo, or Astro, you will notice that --- also serves as the delimiter for front matter blocks at the top of markdown files:

---
title: My Blog Post
date: 2026-05-11
---

Content starts here.

The parser distinguishes between front matter and horizontal rules based on position. The triple hyphens at the very beginning of a file open a front matter block, while the same characters elsewhere in the document create a horizontal line. Keep this in mind so you do not accidentally break your front matter by adding extra --- lines near the top of your file.

Quick Reference

Here is a summary of every way to add a horizontal line in markdown:

• --- (three hyphens) is the most common and widely supported syntax.
• *** (three asterisks) works identically and avoids accidental heading creation.
• ___ (three underscores) is fully supported but less commonly used.
• Always leave a blank line above the horizontal rule to prevent it from being interpreted as a heading.
• All three methods work in GitHub markdown.
• Discord does not support markdown horizontal lines natively.

Final Thoughts

Learning to add a horizontal line in markdown takes only a moment, but using it well requires a bit of judgment. Pick one syntax style, stay consistent throughout your documents, and remember to include a blank line above the rule to avoid formatting surprises. With these basics in place, your markdown documents will be cleaner, more readable, and better organized.