md-document

md-document — 長文 Markdown から HTML へ

汎用コンバーターです。Shihipar が説明するケースの 90％（仕様書、計画書、RFC、レポート、解説資料）に対応します。標準ライブラリの 3 つのツールを連携させます。

markdown_parser.py  →  html_renderer.py  →  interactivity_injector.py
   (md → JSON AST)    (AST + tokens → HTML)    (HTML + JS behavior)

出力は、固定表示の目次、検索フィルター、スクロール位置に応じた目次の強調表示、コードのコピーボタン、ユーザーが導出した 12 個のブランドトークンを備えた .html ファイル 1 つです。外部依存は Google Fonts CSS と Prism.js CDN に限定されます。

呼び出すタイミング

症状	対応
markdown-html-orchestrator が入力を DOCUMENT として振り分ける	このスキルを呼び出します
ユーザーが /cs-md-document <path>.md を直接実行する	このスキルを呼び出します
ユーザーが「この仕様書／レポート／RFC／計画書を HTML に変換して」と言う	このスキルを呼び出します
入力がコードレビューである（```diff ブロックがある）	代わりに md-review に振り分けます
入力がスライドデッキである（明確な --- 区切りがある）	代わりに md-slides に振り分けます
入力が 100 行未満である	拒否します（Shihipar の基準 — Markdown のほうが適しています）
デザインシステムがオンボーディングされていない	拒否し、/cs-design-system を案内します

パイプライン

# 1. Parse markdown → JSON AST
python3 markdown-html/skills/md-document/scripts/markdown_parser.py \
    --input <path>.md --output sections.json

# 2. Render AST + design-system config → single-file HTML
python3 markdown-html/skills/md-document/scripts/html_renderer.py \
    --sections sections.json --output document.html

# 3. Inject lightweight JS (search, copycode, smoothscroll, scrollspy)
python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
    --file document.html \
    --features search,copycode,smoothscroll,scrollspy

または、すべてを一度に実行します（レンダリング例）：

python3 markdown-html/skills/md-document/scripts/html_renderer.py --sample \
  | python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
      --file /dev/stdin --output document.html

レンダリング対象

エージェントが生成する成果物に十分な CommonMark のサブセットです。

• 見出し H1〜H6（H2 以上にはそれぞれアンカー ID と目次項目が付きます）
• インラインの 太字 ／ 斜体 ／ コード ／ リンク ／ を含む段落
• Prism.js によるオンデマンドのハイライトに対応したフェンス付きコードブロック（```python）
• 列ごとの配置に対応した GFM テーブル
• GFM コールアウト（> [!NOTE]、> [!TIP]、> [!IMPORTANT]、> [!WARNING]、> [!CAUTION]）
• 引用、順序付きリストと順序なしリスト（1 階層）、水平線

対象外：入れ子のリスト、インライン HTML、脚注、定義リスト、タスクリストのチェックボックス（プレーンテキストとしてレンダリング）、参照形式のリンク。

厳守事項

1. 100 行未満の入力は拒否します。 基準未満では Markdown のほうが適しています（Shihipar）。
2. オンボーディングなしでは拒否します。 config_loader.setup_completed() が True を返す必要があります。そうでない場合は /cs-design-system を案内します。
3. 出力は単一ファイルです。 CSS と JS はすべてインラインにします。外部依存は fonts.googleapis.com と cdn.jsdelivr.net（Prism）のみです。それ以外はすべてリグレッションです。
4. カスタマイズによって動作を変える必要があります。 design_style=editorial は幅 720px、行間 1.75 のレイアウトを生成します。playful はコールアウトの角を丸くしてシャドウを追加します。technical は 0.875rem のコードを使った高密度の表示になります。スモークテスト済みです。
5. WCAG 準拠のトークンを使います。 デザインシステムの WCAG AA パレットを継承します。本文テキストのコントラスト比は 4.5:1 以上で、リンクも反復調整して 4.5:1 にします。
6. 冪等なインジェクションを行います。 インタラクティブ機能を再注入しても何も起こりません（マーカーを確認）。異なる design_style で再レンダリングしても問題なく動作します。

質問ライブラリ（Matt Pocock の徹底確認スタイル）

1. このドキュメントの目的は何ですか — ざっと読む、判断する、深く読み込む？ 推奨：目的を明記します。情報密度は目的に応じて決めます。参考：Shihipar、Tufte Envisioning Information。
2. 固定サイドバーの目次、それとも折りたたみ可能な上部の目次？ 推奨：800 語超または H2 が 4 つ以上なら固定サイドバー、短くモバイルファーストの文書なら折りたたみ可能な上部の目次です。参考：NN/g TOC Best Practices（2023）。
3. 4 つすべてのインタラクティブ機能を使いますか、それとも一部だけですか？ 推奨：4 つすべてです。どの機能も約 1 KB を超えるコストはかかりません。参考：Wattenberger Why React isn't great for actually building websites。
4. コードのテーマはライト、ダーク、自動のどれですか？ 推奨：自動（OS の prefers-color-scheme に従います）。参考：WCAG 2.2 §1.4.3。
5. ドキュメントに明確な H1 タイトルがありますか？ 推奨：あります。H1 はページの <title> になり、目次からは除外されます。

他との違い

• md-review — このコンバーターは diff ブロックと、重大度タグ付きの余白注釈をレンダリングします。こちらは文章、テーブル、コード、コールアウトをレンダリングします。
• md-slides — このコンバーターは --- 区切りで分割してスライドを作成します。こちらは 1 つの連続したドキュメントをレンダリングします。
• marketing/landing/ — これはランディングページを一から生成します（Markdown 入力はありません）。こちらは既存の Markdown を変換します。

出力成果物

{default_output_dir}/doc-{slug}.html（パスはオーケストレーターの output_path_resolver.py が解決します。デフォルトでは、ファイル名が衝突すると -2、-3、… を付加します）。

参考資料

• Shihipar — Claude Code HTML output（Medium、2026年）
• Tufte — Envisioning Information（1990年）、第2章「Micro/Macro Readings」
• NN/g — Table of Contents Best Practices（2023年）
• WCAG 2.2 — §1.4.3 コントラスト、§2.4.5 複数の方法
• Wattenberger — Why React isn't great for actually building websites
• 出典の全文は references/ を参照してください