Slack markdown
Slack calls its formatting mrkdwn, and the name is the warning. Bold is one asterisk, italic is one underscore, and several things you expect are simply missing.
bold
italic
strikethrough
inline code
a quote
- a bullet
- a numbered item
a code blockSlack's own documentation puts it plainly: mrkdwn is "inspired by markdown, but uses different rules". It is a separate syntax that happens to look familiar, which is why pasting a README into a channel produces a mess rather than a document.
The table below is the whole of it. Anything not in it is not supported, and there is no extension mechanism: what you do instead is restructure the message.
What usually goes wrong
- One asterisk is bold, not italic. Two asterisks show as literal asterisks around bold text, which is what happens to every README pasted into a channel.
- One tilde strikes through; two show as text.
- A language after the opening fence is accepted and ignored. There is no syntax highlighting in Slack.
- Links are
<https://example.com|the text>. The markdown form renders as its own punctuation.
What Slack supports
| Feature | How it works |
|---|---|
| Bold | *bold*, one asterisk. Two asterisks show as literal asterisks around bold text. |
| Italic | _italic_, one underscore. |
| Strikethrough | ~strike~, one tilde. Two show as text. |
| Inline code | ` code `, the same as markdown. |
| Code block | Triple backticks. A language name after the fence is ignored: there is no syntax highlighting. |
| Blockquote | > at the start of the line. |
| Lists | Slack documents no list syntax. Typing - or 1. and a space makes the composer build a list for you, but the underlying text is not markdown. |
| Links | <https://example.com|the text>, angle brackets and a pipe. The square-and-round-bracket form does nothing. |
| Headings | Not supported. Bold on its own line is the usual stand-in. |
| Tables | Not supported. A code block with padded columns is the common workaround, and it is what this site's table generator's Padded option produces. |
| Images | Not supported in message text. Upload the file or paste a URL and let Slack unfurl it. |
| Task lists | Not supported. Checkbox characters or emoji are the workaround. |
Questions
Why does my README look broken in Slack?
Because almost none of it is mrkdwn. Headings, tables, images and task lists have no equivalent, and `**bold**` renders as asterisks around bold text rather than as bold. Paste the file into a snippet or a code block instead, or link to it.
Can I get a table into a Slack message?
Not as a table. The workaround everyone uses is a code block with the columns padded to line up, because a code block is monospaced. Our table generator's Padded option produces exactly that shape.
Sources
Everything above was read from these, not from memory. If a page here disagrees with one of them, the vendor is right and this page is out of date.
On a Mac, this should not need a browser
Double-clicking a .md file opens a text editor full of raw symbols, and the space bar in Finder shows you the same. The Mac app fixes both: it registers as the handler for markdown and adds a Quick Look extension, so the rendered document is one space bar away.
For Mac.