Slack mrkdwn

Slack's custom mrkdwn syntax is not standard Markdown. First identify the receiving field; the same punctuation can mean something different on another Slack surface.

Choose the Rendering System

System	Common surfaces	Example
Slack mrkdwn	Top-level message text (default), Block Kit text objects with type: "mrkdwn", composer/classic unfurl blocks, legacy attachment fields enabled by mrkdwn_in	*bold* <https://example.com|link>
Standard Markdown	markdown block; markdown_text chat method arguments; Work Object string fields/comments with format: "markdown"; Work Object partial-view messages with message_format: "markdown"	**bold** [link](https://example.com)
Structured rich_text	Slack's WYSIWYG/user-message representation and rich_text_input values	Explicit nested JSON elements and style objects
plain_text	Labels, buttons, placeholders, view titles, and any text object that must render literally	No formatting syntax

Do not translate by punctuation alone. For example, *bold* in mrkdwn is italic in standard Markdown. A rich_text block does not parse either syntax; construct its elements explicitly.

Standard Markdown Surfaces

Markdown Block

{
  "type": "markdown",
  "text": "## Result\n\n**Complete** — see [details](https://example.com)."
}

Slack's markdown block explicitly documents support for:

• bold, italic, nested bold/italic, and strikethrough
• ordered and unordered lists
• links, block quotes, inline code, and fenced code blocks
• language-tagged fenced code blocks with syntax highlighting
• headings, horizontal dividers, tables, and task lists
• images, translated to hyperlink text using the image alt text
• backslash escaping of documented special characters

The current block reference says all heading levels render at the same size, while Slack's March 6, 2026 changelog says variable-sized headers are being rolled out. Treat heading size as rollout- and client-dependent rather than relying on a specific visual hierarchy until the references converge. A single input block may translate into multiple output blocks. The cumulative text limit across all markdown blocks in one payload is 12,000 characters. A supplied block_id is ignored and not retained.

markdown_text Chat Arguments

The following current Web API methods accept a standard-Markdown markdown_text argument with a 12,000-character limit:

Methods	Combination rules
chat.postMessage, chat.postEphemeral, chat.scheduleMessage, chat.update	Do not combine markdown_text with blocks or text; Slack returns markdown_text_conflict
chat.startStream, chat.appendStream, chat.stopStream	Accept Markdown during a stream; chat.stopStream can also append final blocks, rendered after streamed Markdown/chunks

Streaming methods also accept chunks. In the current method references, a Markdown chunk is:

{ "type": "markdown_text", "text": "**Streaming** response" }

chunks can also carry task updates, plan updates, and block chunks. Consult the individual streaming method reference for the exact request fields and current limits. Link unfurling is disabled in streaming messages.

Work Objects

Work Objects do not use mrkdwn for their metadata string formatting:

{
  "type": "string",
  "value": "**Blocked** — see [runbook](https://example.com/runbook)",
  "format": "markdown"
}

• A Work Object fields or custom_fields property of type string can set format: "markdown". This is incompatible with that field's icon or link properties.
• Work Object comments can provide { "value": "...", "format": "markdown" }; comments may alternatively provide structured rich-text blocks.
• A custom partial-access message can set message_format: "markdown" for its custom_message.
• To reference a Work Object inside rich_text, use a structured work_object_mention element (including entity_id, app_id, text, and url), not a made-up mrkdwn token.
• Block Kit text objects embedded in composer or classic link unfurls still follow their own mrkdwn/plain_text rules.

mrkdwn Syntax

Format	Syntax	Notes
Bold	*bold*	Not **bold**
Italic	_italic_	Not *italic*
Strikethrough	~strikethrough~	Not ~~strikethrough~~
Inline code	`code`	Other formatting is disabled inside
Code block	Triple backticks around the text	No documented language-tag highlighting in mrkdwn
Block quote	>quoted text	Put > at the start of each quoted line
Link	<https://example.com|display text>	Not [text](url)
Emoji	:emoji_name: or Unicode	Retrieved messages use colon form
Newline	\n in a string	Produces a line break
List-like text	- item / 1. item plus newlines	mrkdwn has no list syntax; these are text conventions

Headings are not mrkdwn syntax. Use a header block, a standard-Markdown markdown block, or structured rich text as appropriate.

For complex combinations, true lists, or user-authored formatting, prefer structured rich_text instead of relying on undocumented marker nesting.

Links and Unfurls

https://example.com
<https://example.com>
<https://example.com|Display text>
<mailto:user@example.com|Email user>

Raw URLs in mrkdwn are normally auto-transformed into links. URLs containing spaces break parsing; remove or URL-encode the spaces. When messages are retrieved, Slack returns auto-transformed URLs in angle-bracket form, sometimes with an explicit label.

Slack normally unfurls links posted by users and apps, including media links in Block Kit blocks. For publishing methods that expose these parameters:

Parameter	Controls
unfurl_links	Primarily text-based content
unfurl_media	Media such as images, video, and audio

Set both to false to suppress all link previews. For messages containing LLM-generated URLs, disable unfurls by default with both unfurl_links: false and unfurl_media: false: Slack warns that its outbound preview request can complete prompt-injection data exfiltration. If previews are required, allow-list trusted external domains and reject or report URLs outside that list. Slack does not unfurl a manually labeled link when the label is a complete substring of the URL after removing the protocol (for example, <http://example.com|example.com>). Streaming messages do not unfurl links.

Custom app unfurls use the renderer of each receiving field. Composer preview elements can contain an object with type: "mrkdwn"; blocks within the unfurl use their normal text-object rules. Exception: chat.unfurl does not currently support rich-text blocks and may return invalid_blocks for an otherwise valid Block Kit payload containing a rich-text section element. A chat.unfurl user_auth_message supports simple Slack formatting, while user_auth_blocks supplies a Block Kit alternative. Work Object entity metadata remains a separate standard-Markdown case as described above.

Mentions and References

Manual, Stable Syntax

<@U0123ABC456>          user mention
<#C0123ABC456>          conversation link
<!subteam^SAZ94GDB8>    user group mention
<!here>                 active channel members
<!channel>              all channel members
<!everyone>             everyone in #general (non-guest workspace members)

An app-published user mention notifies that user. An app-published user group mention notifies the group. Special mentions can notify many people and should be used sparingly.

Use IDs rather than names. User, conversation, and user-group names can change; their IDs are stable. A user who cannot access a referenced private channel sees an unclickable private channel label.

The current chat.postMessage reference says link_names finds and links user groups and no longer supports individual users. Do not depend on name auto-parsing for users, conversations, or special mentions. Use the explicit forms above.

Date Formatting

Slack localizes app-published dates to the timezone setting of the viewer's device, not the timezone preference in their Slack client.

<!date^{unix_timestamp}^{token_string}^{optional_link}|{fallback_text}>

Token	Example behavior
{date_num}	2014-02-18, with leading zeros
{date}	February 18th, 2014
{date_short}	Feb 18, 2014
{date_long}	Tuesday, February 18th, 2014
{date_pretty}	{date}, but uses yesterday/today/tomorrow where appropriate
{date_short_pretty}	{date_short}, but uses yesterday/today/tomorrow
{date_long_pretty}	{date_long}, but uses yesterday/today/tomorrow
{time}	Viewer preference: 6:39 AM or 18:39
{time_secs}	Viewer preference: 6:39:42 AM or 18:39:42
{ago}	Human-readable elapsed time such as 3 minutes ago

{date}, {date_short}, and {date_long} omit the year when the date is less than six months in the past or future. The optional third ^-separated value must be a fully qualified URL and makes the rendered date clickable.

Fallback text is required for older clients. Include a timezone in it because the fallback cannot be localized.

<!date^1392734382^Posted {date_num} {time_secs}|Posted 2014-02-18 6:39:42 AM PST>
<!date^1392734382^{date_short}^https://example.com/|Feb 18, 2014 PST>

Slack returns the original <!date...> string when messages are retrieved.

Escaping

Slack reserves exactly three characters for special parsing. When they are data rather than deliberate control syntax, encode them as:

Character	Entity
&	&
<	&lt;
>	&gt;

Do not HTML-encode the whole string: Slack only decodes these three documented entities. Escape & first, then < and >, to avoid re-encoding the ampersand you just introduced. JSON/string escaping is a separate concern.

Escape untrusted text before placing it in a mrkdwn-capable field. Otherwise it can introduce links, manual mention tokens, or date controls. Prefer plain_text when no formatting is needed.

Text Objects

[
  { "type": "mrkdwn", "text": "*bold* and _italic_", "verbatim": true },
  { "type": "plain_text", "text": "No formatting", "emoji": true }
]

The generic text object allows 1–3,000 characters. A containing block or element may impose a smaller limit; for example, section fields allow up to 10 objects of 2,000 characters each.

• verbatim is valid only for mrkdwn.
• emoji is valid only for plain_text and controls whether Slack escapes recognized emoji into colon format. It does not enable mrkdwn.

verbatim

Value	Behavior
false (default)	Preprocesses plain content: raw URLs become links, conversation names may be linked, and certain mentions may be parsed
true	Skips that preprocessing, while still processing mrkdwn and explicit manual constructs such as <@U…> or <url|label>

Use verbatim: true when content contains raw @, #, or URLs that should not be automatically rewritten. It is not a way to neutralize deliberate angle-bracket control syntax; escape untrusted < and >.

Common Field Rules

This is a practical summary, not a substitute for the receiving component's reference:

Context	Accepted text-object types
Section text and fields	mrkdwn or plain_text
Context text elements	mrkdwn or plain_text
Alert text (modal only, max 200)	mrkdwn or plain_text
Card/carousel-card title, subtitle, body, subtext	mrkdwn or plain_text; field-specific 150/200 limits apply
Checkbox/radio option text and description	mrkdwn or plain_text
Select, multi-select, and overflow option text/description	plain_text only
Header text, button text, placeholders, input labels/hints, view title/submit/close	plain_text only

Slack adds Block Kit components over time. Verify the exact field reference before choosing a text type or limit.

Top-Level Message Text and Parsing

When a message has no blocks, top-level text is the rendered body and uses mrkdwn by default. When blocks are present, top-level text is a fallback rather than visible block content.

For chat.postMessage:

Setting	Current documented effect
default parse	mrkdwn is applied; raw URLs are hyperlinked
parse: "none"	mrkdwn is still applied; raw URL hyperlinking is disabled
parse: "full"	mrkdwn formatting is ignored
mrkdwn: false	Disables mrkdwn processing for top-level text
link_names: true	Finds and links user groups; no individual-user linking

Use explicit ID-based syntax and disable unwanted preprocessing. Slack's formatting guide recommends manual parsing because names can change and automatic parsing can turn third-party input into unintended notifications.

For best results, keep top-level text under 4,000 characters. Slack truncates messages over 40,000 characters. Blocks have their own limits.

Accessibility and Notification Fallbacks

Screen readers default to the message's top-level text and do not read interior blocks directly. With blocks, Slack documents two accessible approaches:

1. Include every necessary piece of content in top-level text.
2. Omit top-level text and let Slack attempt to synthesize it from supported blocks.

Prefer an explicit, complete textual summary when notification and assistive-technology parity matters.

Notification behavior changed in July 2026:

• Desktop notifications extract text from supported blocks first, then fall back to message.text if nothing can be extracted.
• Mobile notifications exclusively use message.text.

Do not assume a richly formatted block layout will produce a complete mobile notification or screen-reader experience.

Structured Rich Text

rich_text is the structured format produced by Slack's user composer and by rich_text_input. Slack's reference strongly prefers it for user-defined formatted text because it is more flexible than mrkdwn.

Use explicit elements such as rich_text_section, rich_text_list, rich_text_quote, and rich_text_preformatted, with nested elements/styles for text, links, emoji, users, channels, user groups, broadcasts, dates, and Work Object mentions. Do not put a mrkdwn string into a rich_text block and expect it to parse.

Legacy Secondary Attachments

Secondary attachments are legacy. Prefer Block Kit for new development. Legacy fields can be subject to reduced visibility or functionality.

• mrkdwn_in is an array naming attachment fields to format as mrkdwn. The documented mrkdwn-capable legacy content is text, pretext, and field-object values via fields.
• A field-object title cannot contain markup and is escaped.
• fallback is a plain-text summary for clients that do not show formatted attachment content.
• Without attachment blocks, one of fallback or text is required.
• Attachment text collapses at 700+ characters or 5+ line breaks.
• Slack allows no more than 20 attachments in a message.

{
  "fallback": "Deployment completed",
  "text": "Deployment *completed*",
  "mrkdwn_in": ["text"]
}

Common Mistakes

Mistake	Correction
**bold** or [text](url) in mrkdwn	Use *bold* and <url|text>
*bold* in standard Markdown	It is italic; use **bold**
# Heading in mrkdwn	Use a header block or standard-Markdown surface
Passing syntax strings to rich_text	Build structured rich-text elements
Combining non-streaming markdown_text with text/blocks	Send one system; Slack returns markdown_text_conflict
Using link_names for user mentions	Use <@USER_ID>; link_names no longer links users
Treating verbatim: true as escaping	Explicit <...> controls still process; escape untrusted &<>
HTML-encoding every character	Encode only &, <, and >
Formatting Work Object fields with mrkdwn	Use standard Markdown plus format: "markdown"
Assuming block text covers every fallback	Supply deliberate top-level text when mobile notifications/a11y require it

Reference Documentation

File	Purpose
references/CHEATSHEET.md	Compact renderer choice, syntax, mentions, dates, parsing, and fallback rules

Official Slack Sources

• Formatting message text
• Text object
• Markdown block
• Variable-sized header rollout — March 6, 2026
• Rich text block
• Alert block and Card block
• Option object
• chat.postMessage, chat.postEphemeral, chat.scheduleMessage, and chat.update
• chat.startStream, chat.appendStream, and chat.stopStream
• Developing an agent — text streaming
• Implementing Work Objects and Work Object comments
• Work object mention element
• Unfurling links in messages
• Security best practices
• chat.unfurl
• Legacy secondary message attachments
• Desktop notification change — July 13, 2026