Discord Markdown Formatting Guide: Bold, Spoilers & Color Code Blocks

1. Understanding Discord's Markdown Engine

Discord relies on a customized parser built on top of the open-source simple-markdown project. Unlike traditional Markdown (like CommonMark or GitHub Flavored Markdown), Discord parses text on the client-side within user chat buffers. This choice enables immediate visual feedback but introduces unique behavior.

For instance, Discord does not support HTML tags, raw tables, or complex image embeds within regular messages. Instead, it relies on its custom syntax. Chat messages are limited to 2,000 characters (or 4,000 characters for Nitro subscribers), making efficient layout styling necessary.

When a message is sent, the desktop, web, or mobile client parses the text. It converts the character sequences into formatted HTML elements inside the chat log window. If the parser detects an invalid sequence or an unclosed tag, it stops parsing and displays the raw formatting characters in the chat window. This design helps users fix their formatting.

The simple-markdown implementation in Discord is optimized for speed and safety. By blocking inline HTML, Discord protects users from cross-site scripting (XSS) risks. By limiting characters, Discord prevents servers from being overloaded by large blocks of text.

2. Basic Text Formatting & Combinations

To format text, you place specific keyboard symbols before and after words. Below is a comprehensive table detailing standard decorations:

Combining Formatting Styles

You can combine formatting options by nesting tags. Order is important: the tags must close in the reverse order they were opened.

<!-- Bold and Italic -->
***bold and italic***

<!-- Underlined Bold -->
__**underlined bold**__

<!-- Underlined Italic -->
__*underlined italic*__

<!-- Underlined Bold Italic -->
__***underlined bold italic***__

<!-- Underlined Bold Strikethrough -->
__**~~underlined bold strikethrough~~**__

If tags are closed out of order, the parser can fail, leaving raw symbols visible in the chat buffer.

For example, writing __**bold and underline__** will fail. The correct syntax is __**bold and underline**__. This strict order is a common troubleshooting area for users setting up server guidelines or automated welcome messages.

3. Organizing Layouts with Headers and Lists

Recent updates have added support for standard headers and lists.

Headers (H1, H2, H3)

Headers format sections, making announcements or lists organized. Type one, two, or three hash characters at the start of a line, followed by a space:

# Main Announcement Title (H1)
## Section Heading (H2)
### Subsection Heading (H3)

A space after the hash markers is required. If omitted, the characters will display as text.

Headers in Discord also add a subtle bottom margin, helping to separate sections. Keep in mind that Discord headers cannot be customized with colors. They inherit the theme font color of the client.

Bullet and Numbered Lists

Create lists by starting lines with dashes (-), asterisks (*), or numbers:

- Item one
- Item two
  - Nested item (indent with two spaces)

1. First step
2. Second step

Lists help break up text in long server messages, making instructions easier to read.

4. Spoilers & Blockquotes

Discord supports spoilers and quote boxes. Spoilers hide text until clicked, and blockquotes group lines together visually.

• Spoiler blocks: Wrap your copy inside double pipes: ||this is hidden||. The text appears as a black block in the chat. Clicking it reveals the text.
• Single Line Quote: Start the line with a greater-than sign and space: > quote line.
• Multi-Line Quote: Start the block with three greater-than signs and space: >>> quote block. All text after this in the message will be quote-styled.

Spoiler tags are useful for community guidelines when discussing plot details or gaming releases. They can also wrap code blocks:

||
```
Hidden code snippet inside spoiler tags
```
||

5. Code Blocks: Inline and Fenced

Code blocks preserve spacing and use a monospaced font. They are useful for error logs, command parameters, and raw snippets.

• Inline Code: Wrap text in single backticks: `git status`. This is used for brief terms within a sentence.
• Fenced Code Block: Wrap text in triple backticks: ```. This is used for multi-line configurations.

Inline code blocks disable text formatting inside them. For example, writing `**bold**` displays the asterisks rather than bolding the text. This behavior is helpful when explaining formatting rules to other users in a chat room.

```
Line one of configuration code.
Line two of configuration code.
```

6. Colored Code Blocks (CSS, YAML, Diff, ANSI)

Discord uses Highlight.js for syntax coloring. You can color your messages by declaring specific programming languages immediately after the first triple backticks.

CSS Syntax Highlighting

The CSS styling profile allows you to color text orange, green, and blue. Classes, IDs, and property names trigger different shades:

```css
.green-class {
  color: #orange;
  font-size: 12px;
}
```

YAML Syntax Highlighting

The YAML formatter highlights values in green and blue. Keys display in blue, while strings and numbers display in green:

```yaml
server_port: 8080
status: "active"
debug_mode: true
```

Diff Syntax Highlighting

The diff highlighting option is useful for showing changes. Lines starting with + display in green. Lines starting with - display in red:

```diff
+ This line is added (Green)
- This line is removed (Red)
*** Header information displays in grey
```

ANSI Color Code Blocks

Discord supports full ANSI escape codes. By using `ansi` after the opening backticks, you can color individual characters. Below is the structure of an ANSI escape sequence:

An escape sequence is structured as: \u001b[STYLE;COLORmYour Text.

• Styles: 0 = Normal, 1 = Bold, 4 = Underline.
• Text Colors: 31 = Red, 32 = Green, 33 = Yellow, 34 = Blue, 35 = Magenta, 36 = Cyan, 37 = White.
• Background Colors: 41 = Red, 42 = Green, 43 = Yellow, 44 = Blue, 45 = Magenta, 46 = Cyan, 47 = White.

```ansi
 [1;31mThis text is bold red [0m
 [4;36mThis text is underlined cyan [0m
 [1;32;44mThis text has green text and blue background [0m
```

Ensure you input the actual escape character (often represented by a small square or symbol depending on your copy source) rather than literal characters.

ANSI coloring is highly useful for bot developer logs, allowing error levels (Red) and success levels (Green) to stand out in channel notifications. Since this is computed client-side, the formatting renders quickly for users checking active log channels.

7. Common Mistakes & Mobile Client Quirks

Writing markdown inside Discord chat buffers can result in formatting errors due to parsing differences:

• Unclosed tags: Forgetting to balance asterisks or pipes will result in the formatting failing, rendering raw symbols inside the chat window.
• Missing spaces in headers: You must place a space between hash indicators and text (e.g. write ## Header, not ##Header).
• Mobile Client Differences: The Discord mobile client on older versions of iOS and Android can render fonts differently. Underline styles and blockquote margins can look misaligned compared to the desktop app.
• ANSI Code Support on Mobile: ANSI escape blocks are not supported on some mobile versions, rendering raw code blocks instead of colors. Ensure announcements are readable in plain text.

In practice, test announcements in a private server channel first. This step ensures that the formatting, headers, and colors align across both desktop and mobile layouts.

Another common issue is character limits. If you reach the 2,000-character boundary, Discord will split your message, which can break unclosed code blocks or spoiler tags. Using an editor to check character counts before posting can prevent this issue.

Finally, remember that bots sending webhooks parse Markdown differently than user inputs. Webhooks support markdown links with custom text: [Link Text](https://url). However, normal users cannot use this syntax in chat channels.