The Complete Discord Markdown Guide
Every Discord markdown format that works — bold, underline, spoilers, headers, subtext, and code blocks — plus the gotchas that catch people coming from GitHub.
Short answer: Discord markdown is a custom subset of markdown, not the standard one. You get *italic*, **bold**, __underline__, ***bold italic***, ~~strikethrough~~, ||spoilers||, `code`, fenced code blocks, > quotes, # through ### headers, -# subtext, lists, and [masked links](url). There are no tables, no markdown images, and no HTML.
The trap is that Discord looks close enough to standard markdown that you assume the rest carries over. It doesn't. __text__ means underline on Discord and bold almost everywhere else, #### does nothing, and pasting a table from a README produces a wall of pipe characters. Here's the whole supported set, what each one does, and where Discord diverges.
The Full Syntax Table
| What you want | Discord syntax | Notes |
|---|---|---|
| Italic | *text* or _text_ | Both work |
| Bold | **text** | Two asterisks only |
| Underline | __text__ | Two underscores — not bold |
| Bold italic | ***text*** | |
| Underline bold | __**text**__ | Combinations nest |
| Strikethrough | ~~text~~ | |
| Spoiler | ||text|| | Two pipes each side |
| Inline code | `text` | |
| Code block | ```lang … ``` | Syntax highlighted |
| Quote | > text | Space after the > is required |
| Block quote | >>> text | Quotes the rest of the message |
| Headers | # , ## , ### | Three levels only |
| Subtext | -# text | Small, muted text |
| Bulleted list | - or * | |
| Numbered list | 1. | |
| Link with custom text | [text](url) | |
| Escape a character | \* | Backslash |
Copy that once and you have most of Discord covered. The rest of this guide is the reasoning and the edge cases.
The Underline Gotcha (Read This One)
This is the single most important difference, and it bites everyone who writes markdown elsewhere:
__this is underlined on Discord__
In CommonMark, GitHub-flavored markdown, Reddit, and almost every other markdown renderer, __text__ is bold. On Discord it is underlined. Discord repurposed the double underscore because standard markdown has no underline syntax at all and chat users kept asking for one.
The practical consequences:
- Text you copy out of a README with
__emphasis__in it will arrive underlined, not bold. - Text you copy out of Discord and paste into GitHub will arrive bold, not underlined.
- If you want bold on Discord, use
**every time. Never__.
Single underscore _text_ is still italic on Discord, matching standard markdown. Only the doubled form is special.
Bold, Italic, and Stacking Them
Discord parses these the way you'd expect once you know the underline rule:
*italic* and _italic_
**bold**
***bold italic***
__underline__
__*underline italic*__
__**underline bold**__
__***underline bold italic***__
Stacking works because Discord applies each wrapper independently. There's no limit on combining them, though anything past two is usually unreadable in a chat window.
One quirk worth knowing: Discord's italic parsing is more forgiving than CommonMark's about underscores inside words. snake_case_name generally survives intact, but if you're posting a lot of identifiers, wrap them in backticks and stop worrying about it.
Strikethrough and Spoilers
Strikethrough is standard:
~~this was wrong~~
Spoilers are Discord's own invention and have no equivalent in standard markdown:
||the butler did it||
The text renders as a solid black bar that reveals on click. You can spoiler part of a line, a whole line, or wrap an attached image by checking "Mark as spoiler" when you upload it. Spoilers also work inside other formatting — **||bold spoiler||** is valid.
Code: Inline and Fenced
Inline code uses single backticks, exactly as you'd expect:
Run `npm install` first.
Fenced blocks use triple backticks, and Discord will syntax-highlight if you name the language on the opening fence:
```python
def greet(name):
print(f"Hello, {name}")
```
Discord supports the common language identifiers — js, ts, py, json, bash, sql, yaml, css, html, xml, diff, md, and many more. If the language name isn't recognized, you still get a monospaced block, just without colors.
Two Discord-specific tricks:
diff for pseudo-colored text. Lines beginning with + render green and lines beginning with - render red inside a diff block. People use this for status lists and changelogs, not just actual diffs.
```diff
+ Server is up
- Backups are failing
```
ansi for real color. Discord accepts an ansi code block where ANSI escape sequences set foreground and background colors. It's fiddly to write by hand and client support has historically lagged on mobile, so don't build anything important on it.
Inside a code block, no other formatting applies. That's the reliable way to show someone raw markdown syntax without Discord eating it.
Quotes
Two forms, and the difference matters:
> This quotes one line.
This line is not quoted.
>>> This quotes everything
after it, including
every subsequent line of the message.
Both require a space after the arrows. >text with no space renders literally. >>> is a one-way door — once you open it, the rest of the message is quoted, so put it last.
There's a Reply button in the Discord UI that creates a proper linked quote of someone's message. Use that for replying to people; use > for quoting text from elsewhere.
Headers and Subtext
Discord added headers to regular messages, but only three levels:
# Big header
## Medium header
### Small header
#### and beyond render as literal hash marks. This trips people up constantly when pasting documentation, because deep heading structures collapse into visible #### noise.
Subtext is the opposite end — small, muted text for footnotes and disclaimers:
-# Prices are approximate and subject to change.
The -# prefix must be at the start of the line, followed by a space. Subtext doesn't stack into levels the way headers do; there's exactly one size.
Lists
Bulleted and numbered lists both work, and they nest:
- First item
- Second item
- Nested item
- Another nested item
- Third item
1. Step one
2. Step two
3. Step three
Discord accepts - or * for bullets. Nesting is by indentation. Numbered lists renumber automatically, so 1. on every line still produces 1, 2, 3 — the same behavior as standard markdown.
Links
Bare URLs autolink. If you want custom link text, use masked link syntax:
Read the [setup guide](https://example.com/setup) before you start.
Masked links work in normal messages on current Discord clients and in embeds sent by bots and webhooks. Because the visible text can differ from the destination, Discord may show a confirmation step before following one — that's an anti-phishing measure, not a bug in your formatting.
To post a URL without the big preview embed underneath it, wrap it in angle brackets:
<https://example.com/very-long-page>
This is one of the most useful pieces of Discord syntax and almost nobody knows it. It's how you paste five links into a channel without producing five preview cards.
Escaping
Backslash escapes any formatting character:
\*not italic\*
\_\_not underlined\_\_
\|\|not a spoiler\|\|
If you're escaping more than a couple of characters, use a code block instead. It's shorter and it can't be misread.
What Discord Does Not Support
Being blunt about the absences saves you time:
- Tables. No pipe-table syntax, no HTML tables. Paste a markdown table into Discord and you get raw pipes. If you need tabular data in a channel, put it in a code block so the columns at least line up in monospace, or post the file.
- Images via markdown.
does not render an image. Upload the file, or paste the bare URL and let Discord's preview embed handle it. - HTML. Nothing. No
<u>, no<br>, no<details>. Discord isn't rendering HTML, it's rendering its own message format. - Horizontal rules.
---on its own line is just three hyphens. - Footnotes, task lists, definition lists, math, or diagrams. None of it.
- Colored text, except through the
diffandansicode block workarounds described above.
There's also a hard length limit on messages — 2,000 characters on a standard account. Long formatted posts hit it faster than you'd think, because every ** counts.
Discord's Flavor Is Its Own Thing
It's tempting to think of Discord as "markdown with a few extras missing." It's more accurate to think of it as a chat formatting language that borrowed markdown's punctuation. It has features standard markdown lacks (spoilers, subtext, underline, embed suppression) and lacks features standard markdown has (tables, images, rules, HTML). Neither is a subset of the other.
That matters most when Discord is one destination among several. If you're drafting an announcement that also goes to a wiki, a README, and an email, write the canonical version in real markdown and adapt it for Discord last — convert __bold__ to **bold**, flatten headings below ###, and replace tables with code blocks or a link.
For anything longer than a few lines, drafting outside the Discord composer is worth it. OpenMark gives you a proper editor with syntax coloring in Markdown view and a rendered preview in Document view, so you can see the structure before you commit to it — then paste the adapted version into Discord. It also means your announcement survives as a file instead of scrolling away in a channel. If you keep a folder of these, our guide to organizing markdown files on Mac covers a sane structure.
Working across other platforms too? The rules change again for Slack, where bold is a single asterisk, and for Reddit, which has superscript and its own spoiler syntax. If you want the standard baseline that everything else diverges from, start with how to write markdown.
Download OpenMark → — $9.99, one-time, native macOS. Draft long-form posts in real markdown, preview them rendered, then adapt for Discord.