書式

mrkdwn と Block Kit rich_text、エスケープ、メンション、リンク、日付トークン、そして素の mrkdwn がブロックに勝る場面

mrkdwn: Markdown に似た別物

Slack の mrkdwn は text オブジェクト（メッセージの text、section のテキスト、context の要素）の中で使う書式構文だ。*bold*、_italic_、~strikethrough~、`code`、そして 引用の > がある。見た目は Markdown に似ているが Markdown の方言ではない。# による見出し 構文も [text](url) によるリンク構文もなく、太字はアスタリスク 2 つ（**bold**）ではなく 1 つ（*bold*）だ。「Slack 版 Markdown」ではなく、それ自体で完結した小さなフォーマットとして 扱うこと。

&、<、> のエスケープ

Slack は text オブジェクト内の特別なパースのために &、<、> を制御文字として使う。 リンクやメンションのトークンを開くわけではない生の < がメッセージ内容に含まれていると、 誤ってパースされてしまう。ユーザー入力など、予測できないテキストを text オブジェクトに 通す前には、この 3 つを必ず HTML エンティティに変換すること。

これは mrkdwn の text オブジェクトに固有の話だ。API 側でコンテンツが自動的にエスケープ されることはないので、外部由来の文字列（ファイル名、ユーザーのコメント、データベースの値）を メッセージに埋め込む bot は、自分でエスケープしなければならない。

メンション、リンク、チャンネル/ユーザーの参照

これらはすべて同じ <token|optional display text> という角括弧の構文を使う。

メッセージ本文中の裸の URL は角括弧なしでも自動リンク化されるが、明示的に囲んだほうが確実で あり、リンクテキストを指定したい時点で必須になる。

日付の書式トークン

<!date^timestamp^token_string^optional_link|fallback_text> は Unix タイムスタンプを クライアント側で、読み手それぞれのロケールとタイムゾーンに合わせてレンダリングする — bot のメッセージで「それは UTC なのか自分の時刻なのか」という曖昧さを避けるための、唯一の 組み込みの手段だ。token_string は次のトークンを 1 つ以上組み合わせて構成する。

例: <!date^1392734382^{date} at {time}|February 18th, 2014 at 6:39 AM PST> — パイプの後ろの フォールバックテキストは、トークンに対応していないクライアント（一部の通知面など）で レンダリングされる内容だ。空のままにせず、トークンの出力を妥当に近似した静的な文字列に しておくこと。

mrkdwn と Block Kit の rich_text

mrkdwn の text オブジェクトは、書式付きの短い文章 — Section ブロックの本文、Context の 1 行、プレーンテキストの通知 — に適した選択肢だ。Block Kit の rich_text ブロックは、 mrkdwn ではきれいに表現できない構造化コンテンツのために存在する。入れ子の箇条書きや 番号付きリスト、独自の見た目のコンテナを持つコードブロック、そして — リストのセクションに 関係するところでは — Slack リストの text 列への書き込みで唯一受け付けられる形式だ （プレーンな文字列はそのまま拒否される。リストの作成を参照）。 単に書式のついたテキストであれば素の mrkdwn を既定とし、コンテンツに本当の構造がある場合 （リスト、1 つの段落に混在するインラインスタイル）や、書き込み先の面が要求する場合に rich_text へ手を伸ばす。

text オブジェクトを含むレイアウトブロックでは、そのオブジェクトの verbatim フィールドを false にすると、上記の角括弧構文で手書きされていないコンテンツ内のメンションやリンクも 自動的にパースされるようになる。外部から取得したテキストをブロックに転載する場合に有用だ。