Strikethrough and Underline
Strikethrough is the marker for “this text is obsolete” or “this option was rejected”, and it is the one piece of formatting in this chapter that Markdown does not define by itself. Two tildes around a phrase are a GitHub Flavored Markdown extension, not part of CommonMark, so the exact same source renders as a struck-through phrase on one site and as a pair of tildes on another. This page explains the correct syntax, which renderers understand it, how it relates to the HTML <del> element, and what to write instead when the platform you publish to does not support it.
Two tildes on each side of a phrase produce the strikethrough:
~~this text is shown with a strikethrough~~<p><del>this text is shown with a strikethrough</del></p>The output element is <del>, the HTML element for text that has been deleted or made obsolete. That is the whole relationship between the two: the Markdown syntax is a shorthand that a GFM-capable renderer expands into that element. Writing <del> by hand produces exactly the same result, but it is raw HTML, so it depends on the renderer allowing raw HTML at all, and in toolchains built on MDX it has to be written as JSX instead.
Who understands it
The feature belongs to GFM, the extension set that GitHub defines on top of CommonMark. Tools built on GFM, which includes GitHub itself, GitLab, and most static site generators once their GFM support is switched on, render the two tildes as intended. A renderer that implements CommonMark and nothing else has no rule for them at all, and prints the tildes as ordinary characters.
That difference is worth knowing before you publish, because the failure is silent. Nothing is reported as an error, the text simply loses its meaning, and a reader sees a sentence peppered with ~~ instead of a sentence with a clearly marked mistake in it. If you are writing for a platform you do not control, either check that it supports the extension or use the fallback described further down.
Why there is no underline
Markdown has no underline syntax at all, and that is a deliberate decision from the very first version of the format: it was created for plain text, where an underline looked like a mistake rather than a style, so the original syntax left it out. The only way to get one is to reach for the inline HTML element (<u>), and that comes with a risk: many renderers strip HTML for security reasons, keeping only a short list of safe tags, and an underline quietly disappears when it does.
Some renderers accept the HTML <ins> element, which marks text as inserted and is displayed underlined by default, as a substitute. It is a better bet than <u> because it is more often on the safe list, but it is still HTML rather than Markdown, and the safe lists differ from one platform to the next.
The practical advice is to reserve the underline for a convention your readers already know, and to use strikethrough for anything that has been withdrawn.
Strikethrough is an inline element like any other, so it can hold code spans, emphasis, and links:
~~contains **bold** strikethrough~~
~~[old link](https://example.com)~~<p><del>contains <strong>bold</strong> strikethrough</del></p>
<p><del><a href="https://example.com">old link</a></del></p>The markers nest as you would expect: ~~**bold**~~ gives a struck-through bold phrase, and **~~bold~~** gives a bold struck-through phrase.
The classic use of strikethrough is marking a feature that has been withdrawn, an option that was rejected, or an old wording that is kept in a revision history for the record. It is an annotation: a reader who scans the page can tell at a glance that this part should not be followed any more.
One caveat is worth making explicit. A strikethrough says “this is void”, not “use this instead”. In a document that people are expected to maintain, pair every struck-through passage with the replacement or the reason it was dropped, otherwise the reader knows that something is gone but not what to do instead. And never use it for content that is still valid, because a page full of struck-through text reads as unreliable as a whole.
| Source | What renders | Why |
|---|---|---|
~~text~~ | strikethrough | the GFM extension syntax |
~text~ | strikethrough in GFM renderers, literal text elsewhere | the specification allows one or two tildes, but the single form is not supported everywhere |
~~ text ~~ | literal text | no space is allowed directly inside the tildes |
~~~~text~~~~ | a code block | four tildes open a fenced code block |
~~text with no closing tildes | literal text | the closing pair is missing |
Strikethrough is an extension, not a basic syntax. In a renderer that implements only CommonMark, ~~text~~ is printed exactly as written, so the reader sees a row of tildes instead of a marked-out phrase. When the destination platform is not under your control, either confirm that it supports GFM or write the status into the words themselves, for example “deprecated: the old endpoint”, and let the text carry the meaning on its own.
Rewrite the sentence below in Markdown. The old endpoint must be marked with a strikethrough, and the new endpoint must be left as normal text with no formatting applied to it.
The old endpoint /v1 was deprecated in 2024; use /v2 instead.Approach:
Strikethrough uses two tildes on each side of the phrase that is obsolete. A single tilde is allowed by the specification but is not supported consistently, so two is the only safe choice. The new endpoint is ordinary text and should not be marked up at all.
Steps:
- Wrap the old endpoint in two tildes on each side, as
~~/v1~~. - Leave the rest of the sentence as plain text.
- Write the new endpoint as plain text, without tildes and without emphasis.
- Check the result: the old endpoint appears struck through, the new one appears normal, and there are no stray tildes left on the page.
Answer:
The old endpoint ~~/v1~~ was deprecated in 2024; use /v2 instead.You should now be able to write strikethrough with two tildes, explain that the syntax is a GFM extension rather than part of CommonMark, and say why a document that relies on it may need a fallback for platforms that do not support the extension. You should also know that the Markdown syntax expands to the HTML <del> element, that Markdown has no underline of its own and that an underline written in raw HTML can be filtered away, and that a strikethrough on its own says only that something is void, never what replaced it. When you next mark withdrawn content in a document, you will pick the markup that says “deprecated” clearly, and add the replacement next to it.