How to underline text in Markdown
Try it - edit the markdown and watch the preview
Visual
There is no Markdown syntax for underline. Not in the original spec, not in CommonMark, not in GitHub Flavored Markdown. Use HTML:
<u>underlined</u>
That renders anywhere HTML is allowed: the editor on this page, a GitHub README, most static site generators.
Use <ins> if the text really was inserted
<ins>added in review</ins>
Browsers underline <ins> by default, so it looks identical, and it carries a
meaning a screen reader can announce. <u> says “draw a line”; <ins> says
“this was added”. If either fits, pick <ins>.
Why the syntax does not exist
On the web, underlined text means a link. Markdown’s whole design is that the raw file reads well as plain text and the rendered output is unsurprising HTML, and an underline mark breaks the second half: readers try to click it.
That is also why no flavour has added one in twenty years, while tables, task lists and strikethrough all arrived as extensions. It is a deliberate absence, not a gap somebody forgot to fill.
What to use instead
| You want | Use |
|---|---|
| Something noticed while skimming | **bold** |
| Emphasis inside a sentence | *italic* |
| A section marker | a heading |
| Text that was added | <ins> |
| A line through, not under | ~~strikethrough~~ |
Where <u> stops working
HTML only renders where the surrounding context renders HTML. <u> will show
as literal characters in a commit message, a plain-text email, most chat
clients, and anywhere a renderer is running in a strict no-HTML mode. In those
places nothing will underline, so fall back to bold.
Common questions
- What is the Markdown syntax for underline?
- There isn't one. No version of Markdown (original, CommonMark or GitHub Flavored) has an underline marker. Bold, italic, strikethrough and code all have one; underline was deliberately left out.
- How do I underline text then?
- With HTML. `<u>text</u>` works anywhere HTML is allowed, including the editor on this page and in a GitHub README. `<ins>text</ins>` is the semantic alternative: it means "inserted text" and browsers underline it by default.
- Why does Markdown have no underline?
- Because on the web an underline means a link. Markdown was designed to read well as plain text and to render to sensible HTML, and a formatting mark whose output is indistinguishable from a hyperlink fails both. Every renderer has kept that decision.
- Does underline work on GitHub?
- Yes, `<u>` survives GitHub's HTML sanitizer in READMEs and issue comments. It does not work in a commit message or anywhere else that renders as plain text.
- What should I use instead?
- Bold for something that must be noticed while skimming, italic for emphasis inside a sentence, and a heading if the underline was really marking a section. If you are underlining because a style guide asks for it, `<ins>` carries the meaning as well as the line.
Sources
- MDN: the u element
- CommonMark spec: raw HTMLwhy an HTML tag is the answer