slack-markdown-parser 2.2.5__tar.gz → 2.3.1__tar.gz

{slack_markdown_parser-2.2.5 → slack_markdown_parser-2.3.1}/CHANGELOG.md

@@ -6,6 +6,27 @@ The format is based on Keep a Changelog, and the project follows Semantic Versio
 
 ## [Unreleased]
 
+## [2.3.1] - 2026-04-10
+
+### Fixed
+
+- Stopped `preserve_visual_blank_lines` from inserting visual-only blank-line placeholders inside fenced code blocks.
+- Kept fallback plain text stable when visual blank-line placeholders are enabled alongside parser-added spacing markers around emphasis or inline code.
+
+## [2.3.0] - 2026-04-10
+
+### Changed
+
+- Documented Slack's March 6, 2026 richer `markdown` block rollout as rollout-dependent in the README and behavior specs, so headers and raw Markdown tables are no longer described as universally stable.
+- Updated maintainer docs with the April 8, 2026 Slack Web rollout observations, including native headers/dividers/task lists/raw Markdown tables and the current blank-line spacing limitation.
+- Extended `scripts/post_slack_render_test.py` with `--transport raw_http|slack_sdk` to compare Web API posting paths while keeping the same markdown payload generation.
+- Split public docs from maintainer QA docs in README / CONTRIBUTING and labeled render-check workflow notes as maintainer-facing rather than end-user package docs.
+- Further reduced README-to-QA coupling by moving maintainer QA doc links behind CONTRIBUTING so the main README stays focused on the public package surface.
+
+### Added
+
+- Added an opt-in `preserve_visual_blank_lines` argument to the main conversion APIs so parser callers can compensate for Slack's currently tight paragraph spacing inside `markdown` blocks without changing fallback plain text.
+
 ## [2.2.5] - 2026-03-14
 
 ### Fixed

{slack_markdown_parser-2.2.5 → slack_markdown_parser-2.3.1}/MANIFEST.in

@@ -1,10 +1,11 @@
 include LICENSE
 include README.md
 include README-ja.md
-include CONTRIBUTING.md
 include CHANGELOG.md
-recursive-include docs *.md
+include docs/spec.md
+include docs/spec-ja.md
+exclude CONTRIBUTING.md
 prune docs/_internal
-recursive-include tests *.py *.md
+prune tests
 recursive-include slack_markdown_parser py.typed
-global-exclude __pycache__ *.py[cod]
+global-exclude __pycache__ *.py[cod] .DS_Store

{slack_markdown_parser-2.2.5 → slack_markdown_parser-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slack-markdown-parser
-Version: 2.2.5
+Version: 2.3.1
 Summary: Convert LLM Markdown into Slack Block Kit markdown/table messages
 Author: darkgaldragon
 License-Expression: MIT
@@ -31,67 +31,84 @@ Dynamic: license-file
 
 # slack-markdown-parser
 
-`slack-markdown-parser` is a Python library that converts standard Markdown generated by LLMs into Slack Block Kit messages built from `markdown` and `table` blocks.
+`slack-markdown-parser` is a Python library that converts ordinary Markdown generated by LLMs into Slack Block Kit messages built from `markdown` and `table` blocks.
 
 ## Why this library exists
 
 Many Slack AI bots have traditionally converted model output into Slack-specific `mrkdwn`, but that approach creates a few recurring problems:
 
-- Conversion overhead: LLMs naturally generate standard Markdown, so `mrkdwn` usually requires extra transformation logic or prompt constraints.
-- Unstable formatting in languages without word spacing: in Japanese and similar scripts, Slack can fail to interpret `*`, `~`, and related markers correctly, exposing the raw punctuation.
-- No table syntax in `mrkdwn`: Markdown tables need custom fallback rendering if you stay in the old format.
+- Extra conversion work: LLMs naturally generate ordinary Markdown, so `mrkdwn` usually needs extra conversion logic or stricter prompts.
+- Unstable formatting in languages without spaces between words: in Japanese, Chinese, Korean, and similar writing systems, Slack can fail to interpret `*`, `~`, and related markers correctly, exposing the raw punctuation.
+- No table syntax in `mrkdwn`: if you stay in the old format, Markdown tables need custom table rendering.
 
 ## Design approach
 
-This library leans on Slack Block Kit's `markdown` block for standard Markdown and `table` block for tables.
+This library uses Slack Block Kit `markdown` blocks for regular Markdown and `table` blocks for tables.
 
 | Problem | Approach |
 |---|---|
-| Conversion overhead | Send standard Markdown through Slack `markdown` blocks without rewriting it into `mrkdwn`. |
-| Formatting instability | Prefer zero-width spaces (ZWSP, U+200B) around formatting tokens, and fall back to locale-aware visible-space padding for CJK nested inline-code cases where Slack rendering still breaks. |
+| Extra conversion work | Send ordinary Markdown through Slack `markdown` blocks without rewriting it into `mrkdwn`. |
+| Formatting instability | Prefer zero-width spaces (`U+200B`) around formatting markers, and only add visible spaces in a few language-specific cases where Slack still renders Japanese, Chinese, or Korean text incorrectly. |
 | No table syntax in `mrkdwn` | Detect Markdown tables and convert them into Slack `table` blocks, including repair of common LLM-generated table inconsistencies. |
 
-The target is natural rendering on Slack, not full CommonMark or HTML fidelity.
+The goal is natural rendering on Slack, not full CommonMark or HTML fidelity.
 If Slack itself does not support a construct in `markdown` blocks, this library prefers safe plain-text rendering or explicit `table` blocks over aggressive rewrites into old `mrkdwn`.
 
 ## Features
 
-- Convert standard Markdown into Slack `markdown` blocks
+- Convert ordinary Markdown into Slack `markdown` blocks
 - Convert Markdown tables into Slack `table` blocks
 - Repair common LLM table issues such as missing outer pipes, missing separator rows, mismatched column counts, and empty cells
 - Split output into multiple Slack messages when needed to satisfy Slack's "one table per message" constraint
-- Sanitize ANSI/control characters and neutralize invalid Slack angle-bracket tokens before block generation
-- Add ZWSP around inline formatting tokens to reduce rendering issues outside fenced code blocks, while preserving English-like punctuation-only boundaries that Slack already renders reliably
-- Use locale-aware visible-space padding for nested inline-code emphasis in dense Japanese, Chinese, and Korean text when Slack requires stronger boundaries than ZWSP alone
-- Support Markdown and Slack-style links inside table cells
-- Build fallback text for `chat.postMessage.text` from generated blocks, normalizing synthetic ZWSP and any parser-inserted visible-space padding used only for rendering stability
+- Remove ANSI/control characters and neutralize invalid Slack angle-bracket tokens before block generation
+- Add zero-width spaces around inline formatting markers to reduce rendering issues outside fenced code blocks, while preserving English-like punctuation-only boundaries that Slack already renders reliably
+- Add visible spaces for a small set of nested inline-code cases in dense Japanese, Chinese, and Korean text when zero-width spaces alone are not enough
+- Support Markdown links and Slack-style links inside table cells
+- Optionally keep blank lines visible inside Slack `markdown` blocks by inserting placeholder lines, while keeping preview text unchanged
+- Build preview text for `chat.postMessage.text` from generated blocks, removing the invisible or temporary spacing that was added only to stabilize Slack rendering
 - Accept raw LLM Markdown without tightly constraining the model prompt, using best-effort sanitize and table repair before Slack delivery
 
-## Observed Slack behavior
+## How Slack behaved in testing
 
 The library is built around how Slack actually renders `markdown` and `table` blocks in practice.
 
+Slack updated its [`markdown` block docs](https://docs.slack.dev/reference/block-kit/blocks/markdown-block/)
+and [changelog entry](https://docs.slack.dev/changelog/2026/03/06/block-kit-rich-text)
+on March 6, 2026 to describe broader support for headings, dividers, task lists,
+native Markdown tables, and syntax-highlighted code blocks. In the Slack Web
+workspace used for this project's April 8, 2026 validation, raw `markdown`
+blocks rendered those constructs natively, including distinct heading levels
+for `#`, `##`, `###`, and setext headings.
+
+Slack still controls the exact release timing and visual style of those newer
+features. Treat newer raw Markdown rendering as behavior controlled by Slack,
+not by this library, and verify it in your own workspace, client, and posting
+path.
+
 Reliable in current Slack rendering:
 
 - `**bold**`, `*italic*`, `~~strike~~`, inline code, and fenced code blocks
-- Bare URLs, autolinks, Markdown links, reference-style links, and mailto links
+- Bare URLs, `<https://...>` style links, Markdown links, reference-style links, and mailto links
 - Bullet lists, ordered lists, task lists, and simple blockquotes
 - Explicit Slack `table` blocks generated from Markdown tables
+- In environments where Slack has enabled the newer renderer, raw Markdown headings, dividers, and tables inside `markdown` blocks
 
 Known Slack-side limitations:
 
-- Heading syntax (`#`, setext headings) renders as plain text rather than true heading levels
-- Nested blockquotes are weak compared with full Markdown renderers
-- Horizontal rules render more like line text than semantic separators
+- Exact heading sizes and some newer raw Markdown features still depend on the Slack app, workspace, and release state
+- Paragraph breaks inside `markdown` blocks currently get little or no extra vertical spacing in tested Slack Web clients, so blank lines can look visually collapsed
+- Nested blockquotes are weaker than in full Markdown renderers
+- Raw Markdown tables inside `markdown` blocks now render in some newer Slack environments, but explicit Slack `table` blocks remain the reliable option across workspaces and delivery paths
 - Markdown image syntax does not become an embedded image in `markdown` blocks
 - Math, raw HTML, HTML comments, `<details>`, admonition syntax, and Mermaid are rendered as plain text or code, not as rich features
 
 What this library compensates for:
 
 - Normalizes underscore emphasis (`_..._`, `__...__`) into Slack-friendly asterisk emphasis
-- Wraps bare URLs into Slack-friendly autolink form before sending `markdown` blocks
+- Wraps bare URLs into Slack-friendly `<https://...>` link form before sending `markdown` blocks
 - Repairs malformed LLM-generated tables before converting them into Slack `table` blocks
 - Keeps table-like rows inside fenced code blocks out of table normalization
+- Optionally turns internal blank lines into placeholder lines that keep paragraphs visibly separated in Slack `markdown` blocks
 - Neutralizes invalid Slack angle-bracket tokens such as raw HTML-like tags
 
 ## Requirements
@@ -121,11 +138,19 @@ markdown = """
 | UI | *In progress* |
 """
 
-for payload in convert_markdown_to_slack_payloads(markdown):
+for payload in convert_markdown_to_slack_payloads(
+    markdown,
+    preserve_visual_blank_lines=True,
+):
     print(payload)
 ```
 
 `convert_markdown_to_slack_messages` automatically splits output into multiple messages when the input contains multiple tables.
+Set `preserve_visual_blank_lines=True` when you want the parser to compensate
+for Slack's currently tight paragraph spacing inside `markdown` blocks.
+The blank-line workaround is intentionally narrow: it skips table segments and
+avoids inserting placeholder lines right before setext heading underlines or
+reference-link definitions.
 
 ## Rendering example
 
@@ -150,7 +175,7 @@ API | **In progress** | Team A
 UI | *Under review* | Team B
 QA | ~~On hold~~ | Team C
 
-> Note: production rollout is scheduled for 2026-03-08 10:00 JST
+> Note: production release is scheduled for 2026-03-08 10:00 JST
 
 1. Finalize release notes
    1. Unify change labels
@@ -174,25 +199,33 @@ Example Slack bot rendering (`markdown` + `table` blocks):
 
 | Function | Description |
 |---|---|
-| `convert_markdown_to_slack_messages(markdown_text) -> list[list[dict]]` | Convert Markdown into Slack messages already split around table blocks. |
-| `convert_markdown_to_slack_payloads(markdown_text) -> list[dict]` | Convert Markdown into Slack-ready payloads with both `blocks` and fallback `text`. |
-| `convert_markdown_to_slack_blocks(markdown_text) -> list[dict]` | Convert Markdown into a flat Block Kit block list. |
-| `build_fallback_text_from_blocks(blocks) -> str` | Build fallback text suitable for `chat.postMessage.text`. |
+| `convert_markdown_to_slack_messages(markdown_text, *, preserve_visual_blank_lines=False) -> list[list[dict]]` | Convert Markdown into Slack messages already split around table blocks. |
+| `convert_markdown_to_slack_payloads(markdown_text, *, preserve_visual_blank_lines=False) -> list[dict]` | Convert Markdown into Slack-ready request data with both `blocks` and preview `text`. |
+| `convert_markdown_to_slack_blocks(markdown_text, *, preserve_visual_blank_lines=False) -> list[dict]` | Convert Markdown into a flat Block Kit block list. |
+| `build_fallback_text_from_blocks(blocks) -> str` | Build preview text suitable for `chat.postMessage.text`. |
 | `blocks_to_plain_text(blocks) -> str` | Convert blocks into plain text. |
 
+`preserve_visual_blank_lines=True` replaces internal blank lines in non-table
+Markdown segments with lines that contain only a non-breaking space. Those
+placeholder lines are removed again when generating preview plain text, so Slack
+notifications and logs stay close to the original Markdown source.
+The current implementation deliberately skips blank runs that sit immediately
+before setext-heading underlines or reference-link definitions, because those
+boundaries can change Markdown meaning in newer Slack Markdown rendering.
+
 ### Utility functions
 
 | Function | Description |
 |---|---|
 | `normalize_markdown_tables(markdown_text) -> str` | Normalize Markdown table syntax before conversion. |
-| `add_zero_width_spaces_to_markdown(text) -> str` | Insert ZWSP around formatting tokens where Slack needs stronger boundaries. |
+| `add_zero_width_spaces_to_markdown(text) -> str` | Insert zero-width spaces around formatting tokens where Slack needs stronger boundaries. |
 | `decode_html_entities(text) -> str` | Decode HTML entities before parsing. |
 | `sanitize_slack_text(text) -> str` | Remove ANSI/control noise and neutralize invalid Slack angle-bracket tokens. |
-| `strip_zero_width_spaces(text) -> str` | Remove ZWSP (`U+200B`) and BOM (`U+FEFF`) while preserving join-control characters such as ZWJ. |
+| `strip_zero_width_spaces(text) -> str` | Remove zero-width spaces (`U+200B`) and BOM (`U+FEFF`) while preserving join-control characters such as ZWJ. |
 
 ### Lower-level exported helpers
 
-These are also part of the public package surface:
+These are also part of the public package API:
 
 - `add_zero_width_spaces`
 - `convert_markdown_text_to_blocks`
@@ -206,9 +239,6 @@ These are also part of the public package surface:
 
 - Behavior spec: [docs/spec.md](docs/spec.md)
 - Japanese behavior spec: [docs/spec-ja.md](docs/spec-ja.md)
-- Slack render-test workflow: [docs/slack-render-test-workflow.md](docs/slack-render-test-workflow.md)
-- Nested-modifier findings: [docs/slack-nested-modifier-findings.md](docs/slack-nested-modifier-findings.md)
-- Desktop/mobile manual checklist: [docs/slack-client-manual-checklist.md](docs/slack-client-manual-checklist.md)
 - Non-goals:
   - Generating Slack `mrkdwn` strings
   - Supporting clients or MCP tools that can only send `mrkdwn`
@@ -216,7 +246,7 @@ These are also part of the public package surface:
 ## Contributing
 
 Contributions, bug reports, and documentation improvements are welcome.
-Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request.
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request. Maintainer-facing Slack renderer QA notes are linked from there rather than treated as part of the end-user package docs.
 
 ## Changelog
 

slack_markdown_parser-2.3.1/README-ja.md

@@ -0,0 +1,200 @@
+# slack-markdown-parser
+
+LLM が生成するふつうの Markdown を、Slack Block Kit（`markdown` + `table` ブロック）に変換する Python ライブラリです。
+
+## 背景
+
+Slack で AI BOT を動かすとき、従来は Slack 独自の `mrkdwn` 形式に変換することが多かったのですが、次の課題がありました。
+
+- 変換の手間: LLM はふつうの Markdown を出力するため、`mrkdwn` に合わせた変換ロジックや厳しいプロンプト制御が必要になりやすい
+- 装飾の崩れ: 日本語・中国語・韓国語のように単語間に空白を入れない文では、`*` や `~` などの装飾記号がうまく解釈されず、そのまま見えてしまうことがある
+- テーブル非対応: `mrkdwn` には表の構文がないため、表をリストなどへ作り替える必要がある
+
+## 設計方針
+
+Slack Block Kit の `markdown` ブロックと `table` ブロックを使って、上の課題に対応します。
+
+| 課題 | 解決手段 |
+|---|---|
+| 変換の手間 | `markdown` ブロックがふつうの Markdown を受け取れるので、LLM 出力を `mrkdwn` に書き換えずに使う |
+| 装飾の崩れ | 基本はゼロ幅スペース（`U+200B`）で装飾記号の境界を補い、それでも崩れる一部の日本語・中国語・韓国語のケースだけ可視スペースを使う |
+| テーブル非対応 | Markdown テーブルを見つけて `table` ブロックに変換し、LLM が作りがちな表の崩れも自動で補う |
+
+このライブラリの目標は、CommonMark や HTML を完全再現することではなく、Slack 上で自然に読める表示を作ることです。
+Slack の `markdown` ブロック自体が対応していない構文は、古い `mrkdwn` へ無理に書き換えるより、安全なプレーンテキスト表示や `table` ブロック化を優先します。
+
+## 主な機能
+
+- ふつうの Markdown テキストを `markdown` ブロックに変換
+- Markdown テーブルを `table` ブロックに変換
+- LLM が生成する表で起こりやすい崩れ（外枠パイプ不足、区切り行不足、列数不一致、空セル）を補正
+- テーブルごとにメッセージを自動分割し、Slack の「1メッセージ1テーブル」制約に対応
+- ANSI escape / 制御文字を除去し、不正な Slack 角括弧トークンを無害化
+- フェンスドコードブロック外では、装飾記号の前後にゼロ幅スペースを入れて表示崩れを減らす
+- 日本語・中国語・韓国語の詰まった文で、インラインコードを含む装飾が崩れる一部のケースでは可視スペースを補って安定化
+- テーブルセル内の Markdown リンク / Slack 形式リンクを認識
+- `markdown` ブロック内の空行が見えにくい環境向けに、内部空行だけを補助用の行へ置き換える `preserve_visual_blank_lines` オプションを用意
+- `chat.postMessage.text` 用のプレビュー文字列を生成し、Slack 表示を安定させるために入れた補助文字はそこで自然な形に戻す
+- モデル側で Markdown を厳密に制御しなくてもよいよう、Slack 送信前にできる範囲でサニタイズと表補正を行う
+
+## 実測ベースの Slack の挙動
+
+本ライブラリは、Slack の `markdown` / `table` ブロックが実際にどう見えるかを前提に設計しています。
+
+Slack は 2026-03-06 に `markdown` ブロックの公式ドキュメントを更新し、見出し、水平線、タスクリスト、表、言語付きコードブロックなど、これまでより多くの Markdown 記法を案内し始めました。ただし、これらの機能は環境ごとに順番に有効化されるとも書かれています。つまり、ワークスペースやクライアントによって見え方が違う可能性があります。
+
+現在の Slack で比較的安定して表示されるもの:
+
+- `**bold**`, `*italic*`, `~~strike~~`, インラインコード, フェンスドコード
+- bare URL, `<https://...>` 形式リンク, Markdown リンク, 参照リンク, mailto リンク
+- 箇条書き, 番号付きリスト, タスクリスト, 単純な引用
+- Markdown テーブルを変換した明示的な Slack `table` ブロック
+- Slack 側で新しい Markdown 表示が有効な環境では、`markdown` ブロック内の見出し・水平線・表
+
+Slack 側の制約として残るもの:
+
+- 見出しサイズや一部の新しい Markdown 表示は、Slack アプリ・ワークスペース・有効化状況に依存する
+- `markdown` ブロック内の段落区切りは、実測した Slack Web では上下の余白がほとんどなく、空行がつぶれて見えやすい
+- 多段引用はフル Markdown レンダラほどきれいに出ない
+- `markdown` ブロック内の生 Markdown テーブルは一部環境では表示されるが、安定性では明示的な Slack `table` ブロックの方が上
+- Markdown 画像記法は `markdown` ブロック内では埋め込み画像にならない
+- 数式, 生 HTML, HTML comment, `<details>`, admonition 記法, Mermaid は特別な表示にならず、テキストまたはコードとして出る
+
+このライブラリが吸収するもの:
+
+- underscore 装飾 (`_..._`, `__...__`) を Slack 互換の asterisk 装飾へ正規化
+- bare URL を Slack の `<https://...>` 形式にそろえる
+- 崩れた Markdown テーブルを補って Slack `table` ブロックへ変換
+- フェンスドコード内の table 風行をテーブル処理から除外
+- 必要に応じて、内部空行を補助用の行に置き換えて段落の区切りを見えやすくする
+- 生 HTML 風タグなど、Slack の特殊記法としては無効な `<...>` 形式を無害化
+
+## 利用前提
+
+- Slack Block Kit の `blocks` で `markdown` / `table` ブロックを送信できる実装が必要です。
+- `text` / `mrkdwn` のみ送信できる経路では利用できません。
+
+## インストール
+
+```bash
+pip install slack-markdown-parser
+```
+
+## 最小利用例
+
+```python
+from slack_markdown_parser import (
+    convert_markdown_to_slack_payloads,
+)
+
+markdown = """
+# Weekly Report
+
+| Team | Status |
+|---|---|
+| API | **On track** |
+| UI | *In progress* |
+"""
+
+for payload in convert_markdown_to_slack_payloads(
+    markdown,
+    preserve_visual_blank_lines=True,
+):
+    print(payload)
+```
+
+`convert_markdown_to_slack_messages` は、複数テーブルを含む入力を Slack 制約に合わせて複数メッセージへ分割します。
+Slack Web の新しい `markdown` 表示で段落間の余白が極端に小さい場合は、`preserve_visual_blank_lines=True` を使うと内部空行だけを見えやすく補えます。
+
+## 入出力イメージ
+
+検証テキスト:
+
+````markdown
+# 週次プロダクト更新
+
+今週は**検索速度改善**と*UI調整*を進めました。旧仕様は~~廃止予定~~です。
+詳細ログIDは`run-20260305-02`です。
+参考: https://example.com/changelog
+
+- APIの**レスポンス改善**
+  - *キャッシュヒット率*を改善
+  - タイムアウト設定を調整
+- バッチ処理の安定化
+  - リトライ回数を統一
+- ドキュメント更新
+
+カテゴリ | 状況 | 担当
+API | **進行中** | Team A
+UI | *確認中* | Team B
+QA | ~~保留~~ | Team C
+
+> 注意: 本番反映は 3/8 10:00 JST を予定
+
+1. リリースノート最終確認
+   1. 変更点の表記統一
+   2. 影響範囲の追記
+2. 監視アラートしきい値調整
+   1. `warning`閾値の更新
+3. QA再確認
+
+```bash
+./deploy.sh production
+```
+````
+
+実際のSlack BOTでの表示例（`markdown` + `table` ブロック）:
+
+![Slack BOT rendering example](Example_ja.png)
+
+## ライブラリの公開インターフェース
+
+### メイン関数（公開関数）
+
+| 関数 | 説明 |
+|---|---|
+| `convert_markdown_to_slack_messages(markdown_text, *, preserve_visual_blank_lines=False) → list[list[dict]]` | Markdown をテーブル分割済みのメッセージ群に変換 |
+| `convert_markdown_to_slack_payloads(markdown_text, *, preserve_visual_blank_lines=False) → list[dict]` | `blocks` とプレビュー用 `text` を含む Slack 送信用データへ変換 |
+| `convert_markdown_to_slack_blocks(markdown_text, *, preserve_visual_blank_lines=False) → list[dict]` | Markdown を Block Kit ブロックのリストに変換 |
+| `build_fallback_text_from_blocks(blocks) → str` | `chat.postMessage.text` 用のプレビュー文字列を生成 |
+| `blocks_to_plain_text(blocks) → str` | ブロックからプレーンテキストを生成 |
+
+`preserve_visual_blank_lines=True` は、非テーブル領域の内部空行を「改行を見えやすくするための補助行」に置き換えるオプションです。
+この補助行はプレビュー文字列を作るときに取り除かれるので、通知文やログは元の Markdown に近い形を保てます。
+また、setext 見出しの下線直前や参照リンク定義直前には補助行を入れず、Markdown の意味が変わらないようにしています。
+
+### ユーティリティ関数（公開関数）
+
+| 関数 | 説明 |
+|---|---|
+| `normalize_markdown_tables(markdown_text) → str` | テーブル記法を正規化（パイプ補完、区切り行生成、列数調整） |
+| `add_zero_width_spaces_to_markdown(text) → str` | 装飾記号の前後にゼロ幅スペースを挿入（フェンスドコードブロック内は除外） |
+| `decode_html_entities(text) → str` | HTML エンティティをデコード |
+| `sanitize_slack_text(text) → str` | ANSI / 制御文字を除去し、不正な Slack 角括弧トークンを無害化 |
+| `strip_zero_width_spaces(text) → str` | ゼロ幅スペース (U+200B) と BOM (U+FEFF) を除去（ZWJ 等の結合制御文字は保持） |
+
+## 仕様
+
+- 挙動仕様: [docs/spec-ja.md](docs/spec-ja.md)
+- 英語仕様: [docs/spec.md](docs/spec.md)
+- 非対応:
+  - `mrkdwn` 文字列の生成
+  - `mrkdwn` のみ送信可能なクライアント／MCP ツール
+
+## コントリビュート
+
+不具合報告、ドキュメント改善、コードの提案を歓迎します。
+Issue / Pull Request を作成する前に [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。Slack 表示のメンテナ向け検証資料は、利用者向け README ではなく CONTRIBUTING 側から案内しています。
+
+## 変更履歴
+
+リリース履歴は [CHANGELOG.md](CHANGELOG.md) で管理しています。
+
+## 連絡先
+
+- GitHub Issue / Pull Request
+- X: [@darkgaldragon](https://x.com/darkgaldragon)
+
+## ライセンス
+
+MIT