slack-mrkdwn

What this skill does

# Slack mrkdwn

Slack's custom text formatting syntax for messages and text objects. Not standard Markdown.

## CRITICAL: Two Markup Systems

Slack has two completely different markup syntaxes. Using the wrong one is the most common formatting mistake.

| System | Used In | Bold | Link | Heading |
|--------|---------|------|------|---------|
| **Slack mrkdwn** | `text` field, text objects (`type: "mrkdwn"`), section fields | `*bold*` | `<url\|text>` | Not supported |
| **Standard Markdown** | `markdown` block only | `**bold**` | `[text](url)` | `# Heading` |

Standard Markdown syntax (`**bold**`, `[text](url)`, `# Heading`) renders as literal text in mrkdwn contexts. Slack mrkdwn syntax (`*bold*`, `<url|text>`) renders as literal text in markdown blocks. Never mix them.

The `markdown` block (`type: "markdown"`) accepts standard Markdown and translates it for Slack rendering. Supports: headings, bold, italic, strikethrough, lists, links, blockquotes, code blocks with optional syntax highlighting, horizontal rules/dividers, tables, task lists, and images (rendered as link text). A single input block may produce multiple output blocks. Cumulative limit across all `markdown` blocks in one payload: 12,000 characters.

## mrkdwn Syntax

| Format | Syntax | Notes |
|--------|--------|-------|
| Bold | `*bold*` | Not `**bold**` |
| Italic | `_italic_` | Not `*italic*` |
| Strikethrough | `~strikethrough~` | Not `~~strikethrough~~` |
| Inline code | `` `code` `` | Same as standard Markdown |
| Code block | ` ```code``` ` | No syntax highlighting in mrkdwn; use a `markdown` block with language-tagged fences for highlighting |
| Blockquote | `> quoted text` | Prefix each line |
| Link | `<https://example.com\|display text>` | Not `[text](url)` |
| Emoji | `:emoji_name:` | Standard or custom. Direct Unicode also works |
| Newline | `\n` | Literal newline in string |
| Ordered list | `1. item` | Plain text, no special rendering |
| Bullet list | `- item` | Rendered properly in `rich_text` blocks only |

Inline code disables all other formatting within it — use it to display literal text like `*not bold*`.

### Nested Formatting

Combining adjacent format markers without spaces (e.g., `*bold*_italic_`) is **unreliable** and may not render correctly. Always add a space between differently-formatted segments:

```
*bold* _italic_              ← works reliably
*bold*_italic_               ← may fail to render
```

For reliable combined formatting on a single word, use `rich_text` blocks with explicit style objects (`{"bold": true, "italic": true}`).

## Links

```
<https://example.com>                            Auto-detected URL
<https://example.com|Display Text>               URL with custom text
<mailto:[email protected]|Email Link>             Email link
```

URLs posted in text are auto-linked by Slack. Use `<url|text>` for custom display text. Spaces in URLs will break parsing — remove them. mrkdwn formatting inside link labels (e.g., `<url|*bold*>`) works for basic styles.

### Link Unfurling

Slack previews ("unfurls") linked content. Control this per message:

| Parameter | Controls | Default (API) |
|-----------|----------|---------------|
| `unfurl_links` | Text-based content previews | `false` |
| `unfurl_media` | Media (images, video, audio) previews | `true` |

Set both to `false` to suppress all previews. These are `chat.postMessage` parameters, not mrkdwn syntax.

## Mentions and References

### User Mentions

```
<@U0123ABC456>
```

Triggers a notification for the mentioned user. Auto-converts to display name.

### Channel References

```
<#C0123ABC456>
```

Auto-converts to channel name. Users without access see "private channel".

### User Group Mentions

```
<!subteam^SAZ94GDB8>
```

Notifies all members of the user group.

### Special Mentions

| Syntax | Scope | Caution |
|--------|-------|---------|
| `<!here>` | Active members in channel | Use sparingly |
| `<!channel>` | All channel members | Triggers push notifications for everyone |
| `<!everyone>` | All non-guest workspace members | Very disruptive |

### Best Practice

Always use IDs, not names. IDs are stable; names change:

```
  <@U0123ABC456>       (user ID)
  @chris                (name — may not resolve)

  <#C0123ABC456>       (channel ID)
  #general              (name — may not resolve)
```

To enable name-based parsing, set `link_names: 1` in the API call. This is fragile and discouraged.

## Date Formatting

Displays dates/times localized to the reader's **device timezone** (not their Slack preference timezone).

### Syntax

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

### Tokens

| Token | Example Output |
|-------|---------------|
| `{date_num}` | 2014-02-18 |
| `{date}` | February 18th, 2014 (omits year if within ~6 months) |
| `{date_short}` | Feb 18, 2014 |
| `{date_long}` | Tuesday, February 18th, 2014 |
| `{date_pretty}` | Yesterday / February 18th, 2014 |
| `{date_short_pretty}` | Yesterday / Feb 18, 2014 |
| `{date_long_pretty}` | Yesterday / Tuesday, February 18th, 2014 |
| `{time}` | 6:39 AM (12h) or 06:39 (24h) |
| `{time_secs}` | 6:39:42 AM |
| `{ago}` | 3 minutes ago / 4 hours ago |

`_pretty` variants use relative terms ("yesterday", "today", "tomorrow") when applicable.

### Examples

```
<!date^1392734382^{date} at {time}|February 18th, 2014 at 6:39 AM PST>
<!date^1392734382^{date_short_pretty} {time}|Feb 18, 2014 6:39 AM>
<!date^1392734382^{ago}|February 18th, 2014>
```

Tokens can be mixed with literal text in the token string. The optional link (third `^`-separated parameter) makes the date a clickable hyperlink. Fallback text (after `|`) displays for clients that cannot render date formatting.

## Escaping

Only three characters require escaping in mrkdwn:

| Character | Escape Sequence |
|-----------|----------------|
| `&` | `&amp;` |
| `<` | `&lt;` |
| `>` | `&gt;` |

Do NOT encode other characters as HTML entities. Only these three are control characters in Slack's markup system.

When displaying user-generated content that may contain these characters, always escape them to prevent unintended formatting or link injection.

## Text Object

The text object is the most common composition object in Block Kit. It determines how text is rendered.

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

`mrkdwn` supports Slack mrkdwn syntax. `plain_text` renders literally. `emoji: true` converts `:emoji:` to rendered emoji (plain_text only). Min 1 char, max 3000 chars (section `fields` max 2000 chars each, max 10 fields).

### Where Each Type Is Allowed

| Context | Allowed Types |
|---------|--------------|
| Header block text | `plain_text` only |
| Section text / fields | `mrkdwn` or `plain_text` |
| Context elements | `mrkdwn` or `plain_text` |
| Button text | `plain_text` only |
| Placeholder | `plain_text` only |
| Input label / hint | `plain_text` only |
| Modal title / submit / close | `plain_text` only |
| Option text | `plain_text` only |
| Option description | `mrkdwn` or `plain_text` |

### Verbatim Behavior

When `verbatim: false` (default):
- URLs auto-convert to clickable links
- Channel names auto-convert to channel links
- Mentions auto-parse

When `verbatim: true`:
- Markdown formatting still processes
- No auto-linking or mention parsing
- Useful for displaying raw URLs or text containing `@` or `#` that aren't mentions

```json
{ "type": "mrkdwn", "text": "Check the log at http://example.com/debug", "verbatim": true }
```

## Auto-Parsing Behavior

### The `parse` Parameter (chat.postMessage)

| Value | Effect |
|-------|--------|
| `"none"` (default) | mrkdwn formatting enabled; minimal auto-parsing of names/URLs |
| `"full"` | Disables mrkdwn formatting; auto-parses URLs, channel names, user mentions |

### Disabling Auto-Parsing

**In text objects:** Set `verbatim: true` (see above).

**In message p