Markdown horizontal line
Three or more dashes on a line of their own draw a horizontal rule. Asterisks and underscores do the same.
The dashes are ambiguous, and that is the whole problem
A line of dashes means two different things depending on what is above it. On its own, with a blank line before it, it is a rule. Directly under a line of text, it turns that text into a heading, which is the older setext form and the reason a rule sometimes swallows the sentence above it instead of appearing.
Underscores and asterisks have no such second meaning, so *** or ___ is the safer choice in a document where the line before is not under your control. Most people use dashes anyway, which is why this comes up as often as it does.
It is a separator, not a divider between sections
A rule between two sections is usually a heading that was not written. Headings give a document a table of contents, anchors and a shape that a screen reader can navigate; a rule gives it a line. Where you meant "a new section starts here", a heading says so and does more.
What usually goes wrong
- Dashes directly under a line of text turn that text into a heading instead of drawing a rule. Leave a blank line between them.
- Three dashes at the very top of a file open YAML front matter, not a rule.
- Spaces between the characters are allowed (
- - -), which occasionally explains a rule you did not expect.
Where it behaves differently
It renders as written on GitHub, GitLab, Obsidian, VS Code preview and Notion. Everywhere else in this table it does something else, and that is worth reading before you paste.
| Platform | Behaviour |
|---|---|
| Discord | Its documentation does not say, so neither do we. |
| Slack | Its documentation does not say, so neither do we. |
For the .md file that arrives in Mail
A markdown file on a phone is the worst case: no editor, no preview, and a share sheet full of apps that want to import it into a library. The iPhone and iPad app opens it where it landed, renders it, and lets you edit and save it back.
For iPhone and iPad.