All posts

Slack Markdown Formatting: What Works and What Doesn't

Slack markdown is not standard markdown — it's mrkdwn. Single-asterisk bold, no headings, no tables, a different link syntax. Here's what works and what doesn't.

Short answer: Slack markdown is not standard markdown. Slack uses its own format called mrkdwn, where bold is a single asterisk (*bold*), italic is a single underscore (_italic_), strikethrough is a single tilde (~strike~), and links in the API are written <https://example.com|text>. There are no headings, no tables, and no markdown image syntax.

This is why pasting a chunk of a README into Slack looks broken. Your **bold** comes out wrong, your ## Heading shows literal hash marks, and your table becomes a pipe soup. The two formats share punctuation and almost nothing else. Here's the complete mrkdwn set, the composer settings that change how it behaves, and a conversion table for moving text between platforms.


The Complete mrkdwn Syntax

FormatSlack (mrkdwn)Standard markdown
Bold*bold***bold**
Italic_italic_*italic* or _italic_
Strikethrough~strike~~~strike~~
Inline code`code``code`
Code block``` … ``````lang … ```
Block quote> quoted> quoted
Link (API)<https://ex.com|text>[text](https://ex.com)
Headingnot supported# Heading
Tablenot supportedpipe table
Imagenot supported inline![alt](url)

Inline code and block quotes are the only two that carry over unchanged. Everything else either differs or doesn't exist.


Bold, Italic, Strikethrough

The pattern is consistent: Slack uses one delimiter character where standard markdown uses two.

*This is bold in Slack.*
_This is italic in Slack._
~This is struck through in Slack.~

If you're used to GitHub-flavored markdown, the single asterisk is the one that will keep catching you. In CommonMark, *text* is italic. In Slack, *text* is bold and _text_ is italic. There's no underline in either.

Doubling the characters is not a supported form. Don't rely on **bold** working — the only syntax guaranteed to render correctly both in the desktop composer and through Slack's API is the single-character version.


Code and Quotes

Inline code works the way you expect:

Run `terraform plan` before applying.

Code blocks use triple backticks:

```
export API_URL=https://example.com
export TIMEOUT=30
```

Here's the important limitation: Slack code blocks have no language tag and no syntax highlighting. You can type ```python out of habit, but Slack doesn't parse it as a language identifier — the word will show up as part of the block's contents. Slack code blocks are monospaced, preformatted text and nothing more.

If you paste a long block of code, Slack may offer to turn it into a snippet — a separate attached file with its own viewer. Snippets do get syntax highlighting and are the better choice for anything more than a handful of lines.

Block quotes use > at the start of the line, same as standard markdown:

> This is the part of the doc I'm asking about.

Links: Two Different Worlds

This is where Slack's split personality shows most.

In the API, a link with custom text is written with angle brackets and a pipe:

<https://example.com/runbook|the runbook>

That's the mrkdwn format your app or webhook must emit. Standard [text](url) markdown is not part of mrkdwn and will post as literal characters.

In the desktop and web composer, the reliable way to create a link with custom text is to select the text and paste the URL over it, or use the composer's link button. Both produce a proper link without you writing any syntax.

Bare URLs autolink everywhere. Slack also has its own bracket-and-angle syntax for non-URL entities that you'll see if you ever read raw message payloads:

Entitymrkdwn
User mention<@U024BE7LH>
Channel link<#C024BE7LR>
Notify the channel<!channel>
Notify people online<!here>
User group<!subteam^SAZ94GDB8>

If you're sending mrkdwn through the API, you also have to HTML-escape three characters in your text: & becomes &amp;, < becomes &lt;, and > becomes &gt;. Skip that step and Slack will try to interpret your angle brackets as one of the entities above.


The Setting That Changes Everything: Markup Mode

Slack's composer is a WYSIWYG editor by default. Type *bold* and the asterisks disappear as you type, leaving bold text behind. Most of the time that's fine. Sometimes it's infuriating — particularly when you're writing about syntax, or pasting text that contains asterisks for other reasons.

There's a preference for this. Open Preferences → Advanced and look for the input option "Format messages with markup." With it enabled, Slack stops applying formatting live in the composer and instead sends your literal markup to be rendered on the message itself. You see the raw *asterisks* while typing, and the formatting appears once the message posts.

Which mode you want depends on how you work:

  • WYSIWYG (default) is better if you use the formatting toolbar and keyboard shortcuts and rarely type markup by hand.
  • Markup mode is better if you write markdown all day and want Slack to behave like every other text box you use.

Either way, the underlying mrkdwn rules are the same. The setting only changes when the formatting is applied, not what's supported.

The formatting toolbar and its shortcuts are worth learning regardless: ⌘B for bold, ⌘I for italic, ⌘⇧X for strikethrough, and ⌘⇧C for inline code. If you want a broader set of editing shortcuts that work in real markdown editors, see our markdown keyboard shortcuts guide.


Why Pasting GitHub Markdown Into Slack Looks Wrong

Here's what happens, line by line, when you paste a typical README chunk into a Slack message:

You pastedSlack shows
# SetupLiteral # Setup — no heading exists
**Important:**Unreliable — use *Important:*
*emphasis*Bold, not italic
~~deprecated~~Unreliable — use ~deprecated~
[docs](https://ex.com)Literal brackets and parens
![screenshot](img.png)Literal text, no image
| col | col |Raw pipes, no table
```pythonCode block containing the word "python"

The fixes, in order of how often you'll need them:

  1. Headings become bold lines. # Setup becomes *Setup* on its own line.
  2. Bold becomes single-asterisk. **x** becomes *x*.
  3. Italic becomes underscore. *x* becomes _x_.
  4. Links get rewritten, or made with the composer's link button.
  5. Tables become a code block so the columns line up in monospace, or an uploaded file, or a link to where the table actually lives.
  6. Images get uploaded as attachments. There is no markdown path.

The table one is the real pain. Slack messages have no table support at all, and the monospace workaround only holds together if you pad the columns by hand. When a table matters, link to the document rather than trying to reproduce it in a message.


Canvases and Block Kit Are Different Surfaces

Two things sit outside the message rules above.

Canvases are Slack's document surface — a separate editing area attached to a channel or standing alone. They have a richer formatting toolbar than the message composer does, so what's true of messages is not automatically true of canvases. If you need a structured document inside Slack, a canvas is the right place for it.

Block Kit is how apps compose messages. Instead of one blob of text, an app sends an array of blocks: section, divider, context, actions, image, header. Inside a section block, the text field can be typed as mrkdwn (formatting applies) or plain_text (formatting is ignored and shown literally).

Block Kit is also the only way to get some things that mrkdwn lacks:

  • A real heading: the header block renders large bold text. Its text field is plain_text only, so no inline formatting inside it, and it's length-limited — keep headers short.
  • A real image: the image block, not markdown syntax.
  • A horizontal rule: the divider block.
  • Lists with proper structure: the rich_text block family, rather than faking bullets with • characters.

If you're building anything that posts to Slack regularly, learning Block Kit is a much better investment than fighting mrkdwn's limits in a plain text field.


A Practical Workflow

The cleanest approach when the same content needs to reach Slack and somewhere else: write it once in real markdown, keep that file as the source of truth, and adapt a copy for Slack at the end.

Drafting in a markdown editor gives you the structure — headings, tables, lists — and a rendered preview to check before you convert anything. OpenMark shows the raw source with syntax coloring in Markdown view and the fully rendered document in Document view, so you can see what you're about to flatten. Then do the Slack pass: headings to bold lines, double delimiters to single, tables to a link.

It's a small amount of extra work, and it means the version that survives isn't the one that scrolled off the top of a channel. Our guide to markdown for technical writing covers structuring those source files well.

Formatting for other chat platforms? Discord uses doubled delimiters like standard markdown but treats __text__ as underline, and Reddit is closest to standard markdown of the three. No two of them agree.


Download OpenMark → — $9.99, one-time, native macOS. Write the real markdown version first, then adapt it for Slack.