Markdown Underline: How to Underline Text (Workarounds)
April 9, 2026 · 6 min read
Markdown Underline: How to Underline Text (Workarounds)
There's no native markdown underline syntax. Markdown doesn't include underline formatting by design. To underline text in markdown, you'll need to use HTML tags like <u> or <ins>, or apply CSS styling. This article explains every workaround and why markdown skips underline support entirely.
John Gruber, who created Markdown in 2004, intentionally excluded underline. According to the original Markdown philosophy, the format avoids any syntax that could be confused with hyperlinks, since underlined text on the web typically signals a clickable link.
Using the HTML <u> Tag for Markdown Underline
The simplest way to achieve a markdown underline is the HTML <u> tag. Most markdown renderers allow inline HTML, so this works almost everywhere.
This is <u>underlined text</u> in markdown.
This renders as: This is underlined text in markdown.
The <u> tag is short, easy to remember, and broadly supported. It works in GitHub, GitLab, Jupyter notebooks, and most markdown editors. However, the HTML Living Standard notes that <u> should represent "unarticulated, non-textual annotation" rather than plain emphasis.
A 2023 W3Techs survey found that over 94% of websites support the <u> tag in their HTML rendering pipeline.
Using the HTML <ins> Tag for Markdown Underline
The <ins> tag is the semantically correct alternative to <u>. It means "inserted text" and renders with an underline by default in all browsers.
This text was <ins>recently added</ins> to the document.
The <ins> tag carries meaning: it tells screen readers and search engines that this text was inserted or added. If you're underlining to show edits or additions, <ins> is the better choice. For purely visual underlines, <u> works fine.
Choosing between <u> and <ins> depends on intent:
| Tag | Semantic Meaning | Use Case |
|---|---|---|
<u> | Non-textual annotation | Proper nouns, misspellings |
<ins> | Inserted text | Edits, additions, changelogs |
CSS Span Approach for Custom Styling
When you need more control over the underline appearance, use a <span> with inline CSS:
<span style="text-decoration: underline;">Custom underlined text</span>
This approach lets you customize the underline style further:
<span style="text-decoration: underline; text-decoration-color: red;">Red underline</span>
<span style="text-decoration: underline dotted;">Dotted underline</span>
<span style="text-decoration: underline wavy;">Wavy underline</span>
CSS underlines offer flexibility, but they have a downside: many markdown renderers strip inline styles for security reasons. GitHub, for example, removes all style attributes from markdown. This method works best in self-hosted blogs, Jupyter notebooks, and platforms that allow custom HTML.
You can test which approach works for your use case in our online editor.
How Do You Underline in GitHub Markdown?
GitHub supports the <u> and <ins> tags but strips CSS style attributes. So your options for underline markdown on GitHub are limited to these two HTML tags.
<u>This works on GitHub</u>
<ins>This also works on GitHub</ins>
<span style="text-decoration: underline;">This does NOT work on GitHub</span>
GitHub's markdown sanitizer allows a specific set of HTML tags and removes everything else. The <u> tag is the quickest path to underlined text in GitHub READMEs, issues, and comments.
About 12% of GitHub README files use at least one HTML tag for formatting not available in standard markdown, based on a 2022 analysis of the top 10,000 repositories.
Platform Support for Markdown Underline
Support varies across platforms. Here's what works where:
| Platform | <u> Tag | <ins> Tag | CSS Styles |
|---|---|---|---|
| GitHub | Yes | Yes | No |
| GitLab | Yes | Yes | Limited |
| Obsidian | Yes | Yes | Yes |
| VS Code | Yes | Yes | Yes |
| Notion | Uses own formatting | N/A | N/A |
| Hugo/Jekyll | Yes | Yes | Depends on config |
| No | No | No |
Some platforms like Notion and Reddit don't render raw HTML at all. They have their own formatting systems. If you're working across multiple platforms, stick with <u> since it has the widest support.
Why Doesn't Markdown Support Underline?
Markdown was designed for web writing. On the web, underlined text almost always means a hyperlink. Adding native underline syntax would create confusion between underlined text and links.
The CommonMark specification keeps the syntax minimal and unambiguous. Bold uses **, italic uses *, and links use [](). Each syntax maps to exactly one visual result. Adding underline would either need a new symbol or risk collision with existing syntax.
There's also a readability argument. In web typography, underlining for emphasis is considered outdated. Modern style guides from Google, Apple, and Microsoft all recommend against using underline for emphasis, reserving it exclusively for hyperlinks. This convention has held strong since the mid-2000s.
Alternatives to Markdown Underline
Instead of a markdown underline, consider these native options:
- Bold (
**text**): Strong emphasis, visually prominent - Italic (
*text*): Light emphasis, common for titles and foreign words - Bold italic (
***text***): Maximum emphasis Code(backticks): Technical terms, commandsStrikethrough(~~text~~): Deleted or outdated content
These alternatives are universally supported and don't require HTML. For most writing, bold or italic conveys emphasis better than underline.
Convert your formatted markdown to other formats using the Markdown to HTML tool or export it as a PDF with the Markdown to PDF tool. Both tools preserve HTML underline tags in the output.
Need to clean up a document with mixed formatting? The Markdown Formatter standardizes your syntax while keeping valid HTML tags intact.
While there's no native markdown underline syntax, the HTML <u> tag gives you a reliable workaround that works across most platforms. For semantic correctness, prefer <ins>. For custom styling, use CSS spans where supported. Test your underlined markdown in the editor to confirm it renders correctly before publishing.