A horizontal line in Markdown lets you separate sections, break the rhythm between two ideas, or simply give the reader a visual pause. It only takes three characters on a line. That is all. But as is often the case with Markdown, it is not always that simple, especially if you switch between GitHub, Obsidian, or a static site generator.

Here is what you need to know about horizontal lines in Markdown, from the basic syntax to the edge cases that can waste your time.

The three possible syntaxes

Markdown supports three ways to create a horizontal line, also called a horizontal rule or thematic break:

---
***
___

Three hyphens, three asterisks, or three underscores. In every case, the HTML output is an <hr> tag.

You can also use more than three characters if you prefer a separator that looks more visible in the raw file:

---------------
***************
_______________

The HTML output is still an <hr> tag. The extra characters do not add any special effect on their own.

A good habit to keep in mind: leave a blank line before and after the horizontal line. It is not an absolute requirement for every Markdown reader or parser, but it is the safest way to avoid problems, especially with ---, which can be interpreted as a level 2 heading in Setext syntax.

This is a paragraph.

---

This is another paragraph.

Hyphens, asterisks, or underscores: which one should you choose?

Functionally, there is no difference. The choice is mostly a matter of convention.

--- is the most common form. You will see it everywhere in GitHub READMEs, documentation, and articles.
*** is sometimes used in more editorial content because some people find it more visual in plain text.
___ works just as well, but it is less common.

The most important thing is consistency. It is better to pick one syntax and stick with it across your files. In practice, --- is the standard.

The most common mistakes

The Setext heading trap

If you write this:

Some text
---

Markdown usually will not render a horizontal line. It will turn Some text into a level 2 heading.

The safest solution is to surround the separator with blank lines:

Some text

---

Confusion with YAML frontmatter

If you use frontmatter in your Markdown files, which is common with Nuxt Content, Astro, Hugo, Jekyll, or other static site generators, your document often starts like this:

---
title: My article
date: 2026-04-13
---

Here, the --- lines do not represent a horizontal line. They are used to delimit metadata.

Confusion usually happens when the frontmatter is not closed properly. In that case, the parser may produce inconsistent output. So it is always worth checking that the block is properly opened and closed.

Spaces between the characters

The following syntaxes are valid:

- - -
* * *
_ _ _

They also produce an <hr> tag. Some people use them to make the source file easier to read, but it is not necessary.

How it behaves on GitHub

GitHub Flavored Markdown supports all three syntaxes.

A few useful points:

in READMEs and wikis, --- is the most common form
in issues and pull requests, horizontal lines also work well to separate context from the actual request
in GitHub Pages, a --- placed at the very top of the file will be interpreted as frontmatter

Here is a common example in an issue:

## Bug report

Steps to reproduce:
1. Open the application
2. Click "Save"

---

**Expected:** the file is saved
**Actual:** error 500

How it behaves in Obsidian

Obsidian supports ---, ***, and ___. In practice, --- is the syntax people use most often.

One thing to know: Obsidian also uses --- for YAML frontmatter. If you place a horizontal line right after that block, it is better to keep a blank line so the file remains compatible with other Markdown renderers.

In reading mode as well as in live preview, Obsidian renders the line as a thin visual separator adapted to the active theme.

Can you change its thickness or style?

Standard Markdown does not let you define the thickness, color, or spacing of a horizontal line. --- simply produces an <hr>.

If you need a custom rendering, you have two options.

Option 1: external CSS

For a website or a blog, this is the best solution:

hr {
  border: none;
  border-top: 3px solid #333;
  margin: 2rem 0;
}

This gives you control over thickness, color, width, and margins.

Option 2: inline CSS in HTML

<hr style="border: 2px solid red;" />

This depends on the rendering tool. Some accept inline HTML, others partially or fully filter it out. For example, GitHub accepts some HTML tags, but strips inline styles, so this example will not produce the expected rendering there. It is less reliable, so it is better to avoid it if you want to keep your Markdown clean.

The best approach is usually this one: keep --- in the content, and handle the styling in the CSS layer.

Can you put a horizontal line inside a table?

No. In a Markdown table, the |---|---| syntax is only used to separate the column headers.

| Name  | Role     |
| ----- | -------- |
| Alice | Dev      |
| Bob   | Designer |

Here, the |-------|-----------| line is not an independent horizontal line. It is part of the table structure.

If you need a real visual separator, the simplest solution is often to split the content into two tables, with a horizontal line between them.

| Team A | Role |
| ------ | ---- |
| Alice  | Dev  |

---

| Team B | Role     |
| ------ | -------- |
| Bob    | Designer |

Quick reference

Syntax	Valid?	Note
`---`	Yes	The most common form. Watch out for the Setext heading trap.
`***`	Yes	A good alternative if you want to avoid confusion with frontmatter.
`___`	Yes	Less common, but supported everywhere.
`- - -`	Yes	Spaces are allowed.
`----`	Yes	More than three characters also works.
`--`	No	Two characters are not enough.

Horizontal lines are among the simplest Markdown elements, but they are also the source of a few annoying traps: Setext headings, YAML frontmatter, or limitations inside tables.

Once you understand these cases, you can use --- confidently in most documents.

If you are also working with tables, you may want to read our dedicated guide: Markdown Table: Complete Guide with Examples.

And if you are looking for a Markdown reader that renders separators, tables, code blocks, and everything else properly across your devices, our Fude app is designed precisely for that.

📌 Download Fude

How to Add a Horizontal Line in Markdown