TL;DR: Slack doesn't use standard Markdown in API messages. It uses its own syntax, called mrkdwn: *bold*, _italic_, ~strike~, `code`, triple backtick code blocks, > quotes, and <https://example.com|links>. Mentions need IDs, such as <@U012AB3CD> or <!here>. If you need standard Markdown features like **bold**, headers, or tables, send your text in a markdown block instead.

This post is a reference for developers who already know Markdown and need to format Slack messages from code. It starts with a cheat sheet and a copy-paste example, then covers each part of mrkdwn in detail.

What is the Slack mrkdwn syntax?

Slack mrkdwn is the markup syntax Slack uses to format message text sent through its API. It looks like Markdown, but it uses different characters for bold, strikethrough, and links, and it adds syntax for Slack-only features such as mentions and channel links. It also leaves out headers and tables.

This quick reference compares each mrkdwn format with its standard Markdown equivalent:

FormatSlack mrkdwnStandard Markdown
Bold*bold***bold**
Italic_italic_*italic* or _italic_
Strikethrough~strike~~~strike~~
Inline code`code``code`
Code block```code``````code```
Block quote> quote> quote
Link<https://knock.app|Knock>[Knock](https://knock.app)
Email link<mailto:[email protected]|Email us>[Email us](mailto:[email protected])
User mention<@U012AB3CD>Not supported
Channel link<#C123ABC456>Not supported
Line break\nBlank line or two trailing spaces
HeadersNot supported (use a header block)# Header
TablesNot supported (use a table block)Pipe syntax

To see several of these formats in one message, here's a copy-paste example that sends a deploy notification with the official Node.js SDK, @slack/web-api. It uses bold text, an emoji, inline code, a user mention, a channel link, and a named link:

import { WebClient } from "@slack/web-api";
 
const slack = new WebClient(process.env.SLACK_BOT_TOKEN);
 
await slack.chat.postMessage({
  channel: "C0123456789",
  // Used for notifications and as a fallback where blocks can't render
  text: "Deploy finished for api-server",
  blocks: [
    {
      type: "section",
      text: {
        type: "mrkdwn",
        text:
          "*Deploy finished* :white_check_mark:\n" +
          "Service: `api-server`\n" +
          "Requested by <@U012AB3CD> in <#C123ABC456>\n" +
          "<https://example.com/deploys/42|View deploy logs>",
      },
    },
  ],
});

Replace the user ID, channel ID, and token with your own values. You can preview any of the payloads in this post in Slack's Block Kit Builder, or mock up a full notification with Knock's Slack preview generator.

Video walkthrough

If you prefer to learn with video, this walkthrough covers the core mrkdwn formats with examples in Slack.

Is Slack mrkdwn the same as Markdown?

No. At first glance, Slack's mrkdwn and the popular Markdown syntax appear similar. Both offer a way to format text using plaintext notation. However, the design and capabilities of each language differ because they serve different purposes.

Markdown was designed as a lightweight markup language to convert plaintext into structurally valid HTML. It enables writers to 'mark up' their text and convert it cleanly into HTML. Most developers know Markdown from GitHub, where you can use it in both the README of a repo and in pull request descriptions. Markdown is also a core component of the Notion platform.

Slack's mrkdwn is a custom formatting syntax tailored to the Slack platform. Its goal is to make it easier to write rich text within Slack and take advantage of core features of the platform, such as @-mentions and channels.

The different purpose leads to core differences in the syntax:

  • Headers. Markdown supports multiple header levels using #. For instance, ### Header 3 represents an <h3> tag in HTML. mrkdwn doesn't support headers at all. To add a header to a message, use a header block, which takes plain_text up to 150 characters.
  • Tables. mrkdwn has no table syntax. Slack now offers a native table block for this. Read how to render tables in Slack markdown for examples.
  • Syntax highlighting. mrkdwn code blocks don't support a language hint. The markdown block does.
  • Mentions and special links. mrkdwn has special formats, like <@U012AB3CD> for user mentions or <!channel> to notify all members of a channel. Markdown has no equivalent, since these features are specific to Slack.
  • Emphasis and links. mrkdwn uses single asterisks for bold and underscores for italics, and it wraps links in angle brackets instead of using square brackets and parentheses.

Where can you use mrkdwn in Slack messages?

mrkdwn is the default format for the top-level text field of chat.postMessage and for Block Kit text objects that set "type": "mrkdwn". Throughout this post, we use Block Kit section blocks to show how to send mrkdwn with the Slack API. Block Kit enables developers to build interactive, structured messages in Slack, and mrkdwn inside those blocks handles the text formatting. For a broader introduction, read our deep dive into Slack's Block Kit.

A few rules to know:

  • Some fields only accept plain_text. For example, header blocks and button labels don't render mrkdwn. The Block Kit reference calls out these fields.
  • Text length limits apply. A section block's text can be up to 3,000 characters, and each item in fields can be up to 2,000 characters.
  • You can turn formatting off. Set a text object's type to plain_text, or set "mrkdwn": false on the top-level text field.

Slack also offers two newer ways to format text. The rich_text block describes formatting as structured JSON elements instead of a markup string, including real bulleted and numbered lists. The markdown block accepts standard Markdown. We cover when to use each one later in this post.

How do you format bold, italic, strikethrough, and code in Slack?

To format text in Slack mrkdwn, wrap it in a single character on each side. Unlike standard Markdown, mrkdwn uses one asterisk for bold, not two, and one tilde for strikethrough:

  • Bold. Wrap your text with asterisks (*) to emphasize a word or phrase.
  • Italic. Wrap your text with underscores (_) to add subtle emphasis or indicate titles of works.
  • Strikethrough. Wrap your text with tildes (~) to indicate corrections or highlight something that's no longer relevant.

mrkdwn also offers two ways to add code to Slack messages. Code formatting helps when your notifications include technical details, such as an alert from an application monitoring platform that shows the code or command that failed.

Inline code is good for highlighting code, commands, or special terminology. For this, you wrap your text with backticks (`). Slack doesn't apply other formatting inside inline code, so it's also useful for text that contains special characters.

Multiline code blocks are ideal for sharing longer code snippets or preformatted text. To create one, wrap your text with three backticks (```). To add a new line, use \n.

Here's how all five formats look in a section block payload:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "This is *bold* \n This is _italic_ \n This is ~strikethrough~ \n This is `code` \n ```This is a code block\nAnd it's multi-line```"
      }
    }
  ]
}

This message reads in Slack as:

Slack message showing bold, italic, strikethrough, inline code, and a code block formatted with mrkdwn

The goal of this formatting is to improve comprehension and draw attention to essential information. Overuse can make messages harder to read. So, while it's tempting to format every message, always prioritize clarity.

You can find all the formatting rules for mrkdwn in Slack's formatting docs.

In Slack mrkdwn, both links and mentions go inside angle brackets. Mentions use IDs, such as <@U012AB3CD> for a user, and links use the format <URL|Displayed text>.

Mentions and links are what turn a notification into something people can act on: mentions get the right people's attention, and links send them to the channel, dashboard, or page where they can respond. The syntax splits into two types: mentions and links inside Slack, and external links to sites and email addresses.

How do you mention a user, group, or channel?

Inside Slack, mentions use IDs wrapped in angle brackets. Writing a name like @scott in app-published text doesn't create a mention. Slack has deprecated automatic name parsing for user mentions, and names can change at any time, while IDs stay the same.

  • Users. <@U012AB3CD>, where U012AB3CD is the user's ID. Slack displays the user's name and notifies them if they're a member of the channel.
  • User groups. <!subteam^SAZ94GDB8>, where SAZ94GDB8 is the user group ID.
  • Special mentions. <!here> notifies active members of a channel, <!channel> notifies all members of a channel, and <!everyone> notifies every non-guest member in the #general channel. As with working in Slack directly, etiquette matters. Don't notify everyone unless you need to.
  • Channels. <#C123ABC456>, where C123ABC456 is the channel ID. Slack displays it as a clickable channel name.

Your app can get user and channel IDs from interaction payloads, Events API payloads, or Web API methods such as users.lookupByEmail and conversations.list. You can also copy a user's member ID from their Slack profile.

To link away from Slack, use the format <URL|Displayed text>. So <https://knock.app|Knock> renders as a clickable link titled "Knock" that leads to https://knock.app. A bare URL also becomes a link automatically. Remove any spaces from URLs, since spaces break them.

You can use this syntax to link to an email address as well by adding the mailto: prefix. So <mailto:[email protected]|[email protected]> renders as a clickable "[email protected]" link that opens the user's default email client.

Here's a payload that combines an external link, a user mention, a special mention, a channel link, and an email link:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "This is a link to the <https://knock.app|Knock website> \n This is a mention of user <@U012AB3CD> \n This is an <!channel> mention \n This is a link to the <#C123ABC456> channel \n This is an email link <mailto:[email protected]|[email protected]>"
      }
    }
  ]
}

Slack replaces the IDs with display names, so this shows in Slack as:

Slack message showing a named link, a user mention, a channel mention, a channel link, and an email link

When you use special links and mentions, consider the context and the intended audience. Mentions are a powerful way to get someone's attention, but they can be disruptive if overused. Likewise, link to channels or external sites with care so the message stays clear and focused.

How do you make lists and blockquotes in Slack?

Slack mrkdwn has no list syntax when you send messages through the API, so you build lists from line breaks and a symbol of your choice. Blockquotes use > at the start of a line, the same as standard Markdown. Both help you break a message into scannable points or call out a specific piece of information.

To create an unordered list, start each line with a symbol, such as a hyphen or a bullet character, and separate the lines with \n:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "- Item 1 \n - Item 2 \n - Item 3 \n - Item 4"
      }
    }
  ]
}

This renders to:

Slack message showing an unordered list built with hyphens and line breaks

Ordered lists use numbers or letters as the symbol. For instance:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "1. Item 1 \n 2. Item 2 \n 3. Item 3 \n 4. Item 4"
      }
    }
  ]
}

This becomes:

Slack message showing a numbered list built with line breaks

If you need real lists with consistent indentation and nesting, use a rich_text_list element inside a rich_text block, or standard Markdown list syntax inside a markdown block.

To add a blockquote to highlight a quotation or important note, start a line with >:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "> This is a blockquote. It can span multiple lines and is often used to highlight specific pieces of information or quotations."
      }
    }
  ]
}

This renders as:

Slack message showing a blockquote formatted with mrkdwn

To quote several lines, start each line with >, for example >First line\n>Second line.

Lists and blockquotes improve readability, but use them with care. Too many lists can confuse readers, and excessive blockquoting dilutes the emphasis you're trying to create.

How do you format dates in Slack messages?

Dates are one of the most useful special formats in mrkdwn, because Slack displays them in each reader's local timezone. You pass a UNIX timestamp with the syntax <!date^timestamp^token_string^optional_link|fallback_text>, like this:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Today is: \n\n <!date^1697250654^{date_short}|Oct 13, 2023> \n <!date^1697250654^{date_short_pretty}|Oct 13, 2023> \n <!date^1697250654^{date_long}|Oct 13, 2023> \n <!date^1697250654^{date_long_pretty}|Oct 13, 2023> \n <!date^1697250654^{date_num}|Oct 13, 2023> \n <!date^1697250654^{date}|Oct 13, 2023>"
      }
    }
  ]
}

This renders as:

Slack message showing one timestamp rendered with six different date tokens

The token string can mix plain text with tokens, so ^Posted {date_short} at {time}^ is valid. Slack supports these tokens:

  • {date_num}. 2014-02-18
  • {date}, {date_short}, and {date_long}. February 18th, 2014, Feb 18, 2014, and Tuesday, February 18th, 2014. Slack omits the year if the date is less than six months in the past or future.
  • {date_pretty}, {date_short_pretty}, and {date_long_pretty}. The same formats, but with "yesterday", "today", or "tomorrow" where appropriate.
  • {time} and {time_secs}. 6:39 AM or 6:39:42 AM, following the reader's 12 or 24 hour setting.
  • {ago}. A relative time, such as 3 minutes ago.

The fallback text after the | is required. Consider including a timezone in it, since it may differ from the reader's timezone.

In JavaScript or TypeScript, use const unixTimestamp = Math.floor(Date.now() / 1000) to get the current time as a UNIX timestamp.

How do you combine formatting and add emoji?

You can combine some mrkdwn formats by nesting one inside another, and you can add emoji with colon shortcodes or Unicode characters. Combining formats helps you emphasize the most important part of a message, such as the link a reader needs to click.

For example, to bold a link, wrap the displayed text in asterisks:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Here is a *bolded* link to <https://knock.app|*Knock*>"
      }
    }
  ]
}

Which renders a bolded link:

Slack message showing a bolded link to the Knock website

To add emoji, use colon shortcodes, such as :rocket:, or paste Unicode emoji into the string. Slack converts Unicode emoji into shortcode format when it stores the message.

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": ":earth_americas: :rocket: :star: :alien: :moon: :sun_with_face: :zap: :fire: :cloud: :umbrella: :rainbow: :cat: :dog: :mouse: :elephant: :tiger: :rooster: :snake:"
      }
    }
  ]
}

This gives us:

Slack message showing a row of emoji added with colon shortcodes

Emoji work well as visual markers for status, such as :white_check_mark: for success or :red_circle: for an error. Like other formatting, they lose their effect when every line has one.

How do you escape special characters in Slack mrkdwn?

Slack uses &, <, and > as control characters for links, mentions, and dates. If you want them to show up as literal characters, replace them with HTML entities:

  • & becomes &amp;
  • < becomes &lt;
  • > becomes &gt;

Only escape those three characters. Don't HTML-encode the entire string, since Slack only decodes these entities. This matters most when you insert user-generated or third-party content into a message, because unescaped text can create unintended links or mentions.

Putting it all together: a mrkdwn alert

To see how these formats work together, let's build an alert that an application monitoring platform might send through Slack. A good alert tells the right people what happened, when it happened, and what to do next. This example uses:

  • Mentions for a specific person or team. The application might get this information from a database of SREs or on-call engineers. Here we use user and user group mentions.
  • A concise description of the alert. Bold text and inline code highlight the issue and the affected service.
  • Links to dashboards and related incidents. These let the team dig into the issue.
  • A list of recommended actions. You can predefine these and add them to the Block Kit payload.
  • A date. This tells anyone who sees the alert when it happened, in their own timezone.
  • Emoji. These act as visual markers that draw attention to each part of the alert.

Altogether, the mrkdwn for this alert is:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "<@U012AB3CD> \n <!subteam^SAZ94GDB8> \n\n *<!date^1697250654^{date_num}|Oct 13, 2023>* \n\n *[APM ALERT]: Elevated Error Rates Detected!* :red_circle: \n - Service: `User Authentication API` \n - Environment: `Production` \n\n :chart_with_upwards_trend: Metrics \n\n *Error Rate*: _15%_ (Threshold: _5%_) \n *Response Time*: _900ms_ (Average: _200ms_) \n *Throughput*: _1200 rpm_ (Requests Per Minute) \n :world_map: Geographical Impact: _US East, Europe Central_ \n  \n :sos: Related Incidents: \n <https://example.com|Database Latency Spike> \n <https://example.com|Redis Connection Failures> \n  \n :link: *Dashboard Link*: <https://example.com|APM Dashboard> \n  \n :speech_balloon: Recommended Actions: \n 1. Verify backend database health and connection. \n 2. Check Redis server and related metrics. \n 3. Assess recent deployments for potential issues."
      }
    }
  ]
}

This code looks complicated, but the monitoring platform adds most of this information dynamically. The result is a well-formatted, clear message for the team:

Slack application monitoring alert combining mentions, a date, bold text, links, lists, and emoji

In this screenshot, the first two lines show @colin and @sres as plain text because we sent names instead of IDs. With the <@U012AB3CD> and <!subteam^SAZ94GDB8> syntax in the payload, Slack renders them as real mentions and notifies those people.

When should you use the markdown or rich text block instead?

Use the markdown block when your content is already in standard Markdown, and use the rich_text block when you need structure that mrkdwn can't express, such as nested lists. mrkdwn covers most notification formatting, but these two newer options fill its gaps:

  • The markdown block. Slack added the markdown block in February 2025 for apps that post AI-generated responses. It accepts standard Markdown, including **bold**, [links](https://knock.app), headers, task lists, code blocks with syntax highlighting, and tables. Slack translates it into its own formatting. The cumulative limit for all markdown blocks in a payload is 12,000 characters. Use it when you already have Markdown, such as LLM output.
  • The rich_text block. The rich_text block describes formatting as JSON elements, such as rich_text_section, rich_text_list, rich_text_quote, and rich_text_preformatted. It's more verbose, but it gives you real nested lists and avoids escaping issues, since you never build a markup string.

Here's a deploy message, like the one from the start of this post, written as a markdown block. Note the double asterisks for bold and the square bracket link syntax:

{
  "blocks": [
    {
      "type": "markdown",
      "text": "**Deploy finished** for `api-server`\n\n- Duration: 4m 12s\n- [View deploy logs](https://example.com/deploys/42)"
    }
  ]
}

Use mrkdwn when you need Slack-specific features like mentions and date formatting in a compact string, the markdown block for existing Markdown content, and the rich_text block when you need precise control over structure.

Frequently asked questions

Does Slack use Markdown?

Not standard Markdown. Slack's API messages use mrkdwn, a Markdown-inspired syntax with different rules. For example, bold is *bold* instead of **bold**, and links use <https://knock.app|Knock> instead of square brackets. Slack's markdown block accepts standard Markdown if you need it.

How do you bold text in Slack mrkdwn?

Wrap the text in single asterisks, like *this*. Double asterisks, which bold text in standard Markdown, don't work in mrkdwn. Use underscores for italics and tildes for strikethrough.

How do you mention a user in a Slack message from the API?

Use the user's ID in angle brackets, like <@U012AB3CD>. Typing a name such as @scott in app-published text doesn't create a mention. For user groups, use <!subteam^ID>, and for special mentions, use <!here>, <!channel>, or <!everyone>.

Does Slack mrkdwn support headers or tables?

No. Use a header block for headers and a table block for tables. The markdown block also renders standard Markdown headers and tables.

Wrap the URL and the displayed text in angle brackets, separated by a pipe, like <https://knock.app|Knock>. For email links, add the mailto: prefix, like <mailto:[email protected]|Email us>. Standard Markdown link syntax, [text](url), doesn't work in mrkdwn.

How do you add a line break in Slack mrkdwn?

Insert a newline character, written as \n in your JSON string. Each \n starts a new line, and two in a row add a blank line. Unlike standard Markdown, trailing spaces don't create a line break.

How do you turn off mrkdwn formatting?

Set a text object's type to plain_text, or set "mrkdwn": false on the top-level text field of your message. To show a literal &, <, or >, escape it as &amp;, &lt;, or &gt;.

Formatting Slack messages in Knock

Leveraging text formatting inside of Slack messages can improve the readability and emphasis of critical information. When time matters and clarity is important, well-formatted notifications are the ones people notice and act on.

At Knock, we've integrated Slack's mrkdwn syntax into our template editor, so you can use the formatting toolbar to draft your content without worrying about exact syntax. It also supports Liquid tags, so you can personalize your Slack notifications however you want.

We also created and maintain SlackKit, a collection of React components, hooks, and APIs to set up Slack in your application so your users can connect their own Slack workspaces.

Here are more posts we've written on building with Slack:

To add Slack notifications to your application, sign up for Knock or reach out to us in our Slack community.