Slack Block Kit Markdown: mrkdwn, the Markdown Block and Lists

Slack Block Kit has two kinds of markup. A text object with "type": "mrkdwn", used in section and context blocks, reads Slack's own syntax: *bold*, _italic_, ~strike~, <https://example.com|link text> and <@U012AB3CD> for a mention. The markdown block, "type": "markdown", reads standard markdown instead: **bold**, [text](url), - lists, # headings and even tables. One markdown block takes up to 12,000 characters; in our test two blocks together passed at 13,200 characters and failed at 13,250. If your text comes from an LLM or a README, use the markdown block. If you build the message yourself and need mentions, dates or buttons, use mrkdwn.

This page covers apps, bots and webhooks. People typing in Slack's composer can now use [text](link) in markup mode, but API and bot mrkdwn still needs <url|text>.

We posted every limit and mention form on this page with a bot token in a test workspace on 4 October; the results are in the tables below. When you cannot use the markdown block, the free Markdown to Slack converter turns standard markdown into mrkdwn.

mrkdwn vs the markdown block

The asterisk is the trap. *this* is bold in mrkdwn and italic in the markdown block. Text written for one reads wrong in the other.

The markdown block

Slack's reference describes the markdown block as the way to post markdown from an LLM without translating it yourself. Slack does the conversion, and one markdown block may turn into several blocks in the posted message.

{
  "blocks": [
    {
      "type": "markdown",
      "text": "## Deploy report\n**Status:** passed\n\n- api: 42 s\n- web: 1 min 10 s\n\n| Service | Version |\n| --- | --- |\n| api | 3.4.1 |\n| web | 3.4.0 |\n\n[Open the run](https://github.com/acme/app/actions)"
    }
  ]
}

Things to know:

• • block_id is ignored and not kept.
• • Images written as ![alt](url) turn into a link with the alt text, not an image. Use an image block for pictures.
• • Task lists (- [ ]) and horizontal rules (---) render.
• • Escape a markdown character with a backslash, such as \*not bold\*.

mrkdwn in section blocks

Most Block Kit layouts still use section blocks with a mrkdwn text object:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Build failed* on `main`\n<https://github.com/acme/app/actions|Open the run> and ping <@U012AB3CD>"
      }
    }
  ]
}

Some fields only accept plain_text, such as header blocks and button labels. In those, asterisks stay asterisks. Slack's developer docs mark which fields allow which type. The top-level text of chat.postMessage uses mrkdwn by default; set "mrkdwn": false to turn formatting off.

Links, mentions and dates in mrkdwn

Link with text          <https://slack.green|Slack Green>
Email link              <mailto:hi@example.com|Email us>
Mention a user          <@U012AB3CD>
Link a channel          <#C123ABC456>
Mention a user group    <!subteam^SAZ94GDB8>
@here, @channel         <!here>  <!channel>  <!everyone>
Date in reader's zone   <!date^1727481600^{date_short} at {time}|Sep 28>

Use the user ID in mentions. A name works in some places and not others. We sent <@sieun> (a username) and <@U0B7L4YK420> (the same person's ID) with a bot token through chat.postMessage:

Where <@sieun> was sent	What Slack posted
Top-level text	A real mention; Slack stored it as <@U0B7L4YK420>
mrkdwn text in a section block	A real mention; stored as <@U0B7L4YK420>
markdown block	The literal text <@sieun>; only the ID form became a mention



In an earlier test a user token resolved the name the same way. This lookup is not in Slack's docs, so build mentions from IDs anyway: a renamed user breaks a name, never an ID. Slack's docs add that a user mentioned by an app is notified only if they are already in the channel. Date strings are easier to build in our Slack timestamp generator, and the full link rules are in how to add a hyperlink in Slack.

Slack treats &, < and > as control characters. Replace them with &, < and > in any text you pass through, and only those three.

For webhook mentions, finding member IDs and a lookup-by-email script, see how to mention a user in a Slack webhook.

Bullet lists in Block Kit

Slack's formatting docs say plainly that there is no list syntax in app-published mrkdwn. You have three options:

Type the bullets. "• first\n• second" in a mrkdwn text. Looks like a list, but long items do not indent when they wrap.

Use the markdown block. - first works there.

Use a rich text block, which gives real, indented lists:

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_list",
      "style": "bullet",
      "elements": [
        { "type": "rich_text_section", "elements": [{ "type": "text", "text": "first item" }] },
        { "type": "rich_text_section", "elements": [{ "type": "text", "text": "second item" }] }
      ]
    }
  ]
}

Use "style": "ordered" for a numbered list. Nested levels, quotes, code blocks and the error each wrong payload returns are in our rich text block tests. People typing in Slack get lists from the composer; see how to make bullet points in Slack.

Test before you send

Paste any payload into Slack's Block Kit Builder to see it rendered; the steps are in how to use Slack Block Kit Builder. For the mrkdwn part alone, the Slack to Markdown side of our Markdown to Slack converter previews the text. If formatting shows up as raw asterisks, Slack markdown not working lists the causes. Length limits for each field are in Slack message character limit, and tables are in how to make a table in Slack.

To post a whole markdown file, such as a README, create a canvas from it instead; see Slack markdown file preview.

Block Kit text limits we measured

Each row is one chat.postMessage call with a bot token:

So the 12,000 figure is per markdown block, and the whole message has a second cap a little above 13,000 characters. Split longer reports across messages.

FAQ

Does Slack Block Kit support markdown? Yes, two ways: mrkdwn text objects with Slack's own syntax, and the markdown block with standard markdown.

What is the difference between mrkdwn and markdown in Slack? mrkdwn is Slack's syntax: *bold*, <url|text>. The markdown block reads standard markdown: **bold**, [text](url).

How do I make a bullet list in Block Kit? Use - item in a markdown block, or a rich_text block with a rich_text_list. mrkdwn has no list syntax.

How do I mention a user in Block Kit? <@U012AB3CD> with the user ID, inside a mrkdwn text.

How long can a markdown block be? 12,000 characters for all markdown blocks in one payload together.