md2html

/md2html

冗長な Markdown ドキュメントを、疲れた人でも実際に読み進められる、単一の自己完結型 HTML ファイルに変換します。段落の代わりに図を、番号付きリストの代わりにステップカードを使い、重要な箇所をコールアウトで示します。

使い方

/md2html <file.md>             # output <file>.html next to source
/md2html <file.md> --out X.html # custom output path
/md2html                       # if no arg, ask user which file

スキルファイル（この SKILL.md からの相対パスで解決）

• template.html — CSS を埋め込んだ HTML の骨組み（Claude のオレンジを基調としたライト／ダークテーマ）、Mermaid CDN、テーマ切り替え、目次サイドバー、フッターが含まれます。{{PLACEHOLDER}} 文字列と `` スロットを含みます。
• components.md — コピーしてそのまま使う必要がある HTML スニペットのカタログ（ステップカード、コールアウト、Mermaid ブロック、メリット・デメリット、比較カード、折りたたみ要素）。
• examples/ — 参照用の <doc>.md → <doc>.html ペアを少なくとも 1 組含みます。作業を始める前に 1 組を読んで、出力品質の基準にしてください。

出力を書く前に、3 つすべてを必ず読んでください。 CSS クラスを独自に作ったり、カタログを省略したりしないでください。

呼び出されたときに行うこと

次の手順を順番どおりに実行してください。省略しないでください。

ステップ 1 — 入力を解決する

1. ユーザーの呼び出し内容からソースファイルを特定します。指定されていない場合は、「変換する .md ファイルはどれですか？」 と尋ねて終了します。
2. ソース .md を最後まで読みます。
3. この SKILL.md と同じディレクトリにある template.html と components.md を読みます。
4. 基準を確認するために、examples/ 内のサンプルペアを 1 組読みます。

ステップ 2 — ソースドキュメントを分析する

この分析は頭の中で黙って行います（または、ユーザー向けに短い要約を 1 行だけ示します）。次の項目を特定してください。

• ソースの言語 — ファイル名ではなく、実際の文章から判定します。<html lang="..."> には ISO 639-1 コード（en、vi、zh、ja、ko、es、fr、de、ru、ar、th など）を設定し、すべての UI ラベルをその言語に翻訳します。

  よく使われる例（同じ方式でほかの言語にも対応してください）。

  Key	EN	VI	ZH (中文)	JA (日本語)	KO (한국어)	ES (Español)
  TOC title	Contents	Mục lục	目录	目次	목차	Contenido
  Read-time	~N min read	~N phút đọc	~N 分钟阅读	~N 分で読了	~N분 소요	~N min de lectura
  Recommended	★ Recommended	★ Đề xuất	★ 推荐	★ 推奨	★ 추천	★ Recomendado
  Key point	Key point	Ý chính	要点	要点	핵심	Idea clave
  Pros	✓ Pros	✓ Ưu điểm	✓ 优点	✓ 長所	✓ 장점	✓ Ventajas
  Cons	✕ Cons	✕ Nhược điểm	✕ 缺点	✕ 短所	✕ 단점	✕ Desventajas
  Print tooltip	Print / Save PDF	In / Lưu PDF	打印 / 保存 PDF	印刷 / PDF 保存	인쇄 / PDF 저장	Imprimir / Guardar
  Theme tooltip	Toggle theme	Đổi theme	切换主题	テーマ切替	테마 전환	Cambiar tema
  Source: prefix	Source:	Nguồn:	来源:	ソース:	소스:	Fuente:

  リストにない言語の場合も、同じ慣例に従って翻訳してください。「Recommended」バッジは、<html> に設定される --rec-label CSS 変数で構成します（言語ごとの CSS は不要です）。詳細は以下の {{REC_LABEL}} を参照してください。

  RTL 言語（アラビア語、ヘブライ語、ペルシア語）— 現在のテンプレートは LTR のみです。ソースが RTL の場合は、<html> に dir="rtl" も追加し、既知の表示上の制約として考慮してください（サイドバーは左側のままです）。

• タイトル — 最初の H1 またはファイル名から決定します。タイトルは 80 文字以内にしてください。

• サブタイトル — H1 の後にある最初の段落、またはドキュメントの TL;DR の文です。200 文字以内にしてください。

• ドキュメントの種類 — 次のいずれかを推定します：PLAN、SPEC、SYSTEM DESIGN、RFC、RUNBOOK、POSTMORTEM、BRAINSTORM、NOTES。ファイル名ではなく、ドキュメントの目的に基づいて最も近いものを選んでください。Brainstorm は理由を示しながら選択肢を探るもの、Plan は目標達成までの順序立てられた手順、Spec は正確な動作仕様、System design はアーキテクチャとトレードオフ、RFC はフィードバックを求める提案、Runbook は運用手順、Postmortem はインシデントのレビューです。アイブロウの大文字コードは共通のままにし、トップバーの BRAND_LABEL はローカライズします（Plan / Kế hoạch / 计划 など）。

• 読了時間 — 単語数を 250 で割り、最も近い分数に丸めます。形式：~N min read（EN）または ~N phút đọc（VI）。

• セクションマップ — 各 H2/H3 を確認し、components.md の §11 の早見表を使って最適なコンポーネントを割り当てます。

  • 番号付きのアクションリスト → Timeline
  • アーキテクチャ／フローの説明 → Mermaid
  • 「長所／短所」、「pros/cons」 → Pros-Cons
  • 「選択肢 A と B の比較」 → Comparison cards
  • 重要な結論 → Key-point highlight
  • 警告／決定事項 → Callouts
  • 長い付録 → Collapsible
  • それ以外 → 通常の <h2> + <p>

ステップ 3 — 出力 HTML を作成する

1. コピー：template.html の内容全体を文字列にコピーします。まだ作成していないファイルに対して、Read-then-Edit は使用しないでください。代わりに、出力バッファをメモリ上で作成してから、一度だけ Write します。
2. プレースホルダーを置換：テンプレート内のプレースホルダーを置換します（すべての値はステップ 2 の分析結果から取得し、言語を一致させます）。
   • {{LANG}} → ISO 639-1 コード：en / vi / zh / ja / ko / es / …
   • {{REC_LABEL}} → 「Recommended」比較カードのバッジに表示するテキスト。例：★ Recommended / ★ Đề xuất / ★ 推荐 / ★ 추천。<html> の --rec-label CSS 変数に設定されます。忘れた場合、CSS は ★ Recommended にフォールバックします。
   • {{TITLE}}（<title> と .doc-title の 2 箇所にあります）
   • {{SUBTITLE}}
   • {{DOC_TYPE}} → 共通の大文字表記コード：PLAN、SPEC、SYSTEM DESIGN、RFC、RUNBOOK、POSTMORTEM、BRAINSTORM、NOTES
   • {{SOURCE_FILE}} → ソースのベース名（例：plan.md）
   • {{DATE}} → ISO 日付、またはローカライズされた「更新日 」
   • {{READ_TIME}} → ローカライズされた読了時間。例：~3 min read / ~3 phút đọc / ~3 分钟阅读
   • {{BRAND_LABEL}} → トップバー用にローカライズされたドキュメントタイプのラベル
   • {{TOC_TITLE}} → ローカライズされた「目次」（TOC ドロワーの aria-label にも使用）
   • {{PRINT_TOOLTIP}} → ローカライズされた印刷ツールチップ
   • {{THEME_TOOLTIP}} → ローカライズされたテーマ切り替えツールチップ
   • {{CLOSE_LABEL}} → ローカライズされた「閉じる」（モバイル TOC ドロワーの閉じるボタンに使用）。例：Close / Đóng / 关闭 / 閉じる
   • {{SKIP_LINK_LABEL}} → ローカライズされたコンテンツへのスキップリンクのテキスト。例：Skip to content / Bỏ qua menu / 跳到正文
   • {{FOOTER_NOTE}} → ローカライズされたソース表記（例：Source: plan.md / Nguồn: plan.md / 来源: plan.md）
3. `` を置換：各 H2/H3 見出しにつき 1 つの <a> に置き換えます（components.md の §2 を参照）。見出しテキストから、安定したケバブケースの id を生成します。
4. と の間のスロットを置換：components.md のコンポーネントを使用して、セクションごとにドキュメント本文を配置します。各セクションは以下を満たす必要があります。
   • <h2 id="..."> で始めます（TOC の項目と一致させます）。
   • 論理的なまとまりごとに主要コンポーネントを 1 つ使用します（コールアウトを 3 つ連続して積み重ねないでください）。
   • 元の意味を保ちます。技術的な詳細を要約して省略せず、冗長な箇所や繰り返しに限って簡潔にします。
5. 書き込み：組み立てた HTML を出力先に書き込みます。

ステップ 4 — 検証

書き込み後、生成したセクションのみを再度読み込み、簡単な健全性チェックを 1 回行います（ファイル全体は読み込まないでください）。

• TOC で参照されているすべての id="..." が見出しに存在すること。
• {{PLACEHOLDER}} 文字列が残っていないこと。
• Mermaid ブロックの構文が有効であること（flowchart、sequenceDiagram、erDiagram、stateDiagram-v2、または gantt を使用し、方向を指定しない graph は使用しないでください）。
• template.html に元から含まれているもの以外に、<script> タグを追加していないこと。

ユーザーには以下を報告してください。

• 出力ファイルのパス
• 変更内容を 1 行で要約（例：「7 セクションをレンダリング：Mermaid フロー 1 件、ステップタイムライン 2 件、コールアウト 4 件。読了時間は約 6 分です。」）
• xdg-open <file>.html（Linux）または open <file>.html（Mac）で開けることを案内してください。

重要なルール

1. 技術的な内容を曖昧な文章に言い換えないでください。 手順に chạy migration 0042_user_schema.sql とある場合は、そのファイル名をそのまま維持してください。「新しいマイグレーションを実行する」に変更してはいけません。
2. チャンクごとにコンポーネントを1つだけ使用してください。 コールアウトをステップカードの中に入れ、さらに折りたたみ可能な要素の中に入れるようなことはしないでください。入れ子構造はフラットに保ってください。
3. 3つ以上の段階があるフローは、文章よりMermaidを優先してください。 ソースに「AがBを呼び出し、BがCを呼び出し、CがDBに書き込む」とある場合は、図にしてください。
4. 重要ポイントの強調は控えめにしてください。 H2セクションあたり最大1つ、ドキュメント全体では2〜3つが理想です。
5. UIテキストは、検出したソース言語に合わせてください。英語やベトナム語以外のソース（中国語、日本語、韓国語、スペイン語など）も対象です。Step 2の言語サンプル表を使うか、同等の翻訳をしてください。コード、コマンド、ファイル名、ライブラリ名、エラーメッセージは、言語にかかわらず原文のままにしてください。
6. 出力は自己完結させてください。 template.htmlにすでにあるCDNスクリプト以外の外部ファイルは参照しないでください。
7. template.htmlやcomponents.mdを変更しないでください。これらはスキルの信頼できる情報源です。Writeするのは出力の.htmlファイルのみです。
8. アイコンにはSVGのみを使用し、絵文字は使わないでください。 すべてのアイコンは<svg class="..."><use href="#i-NAME"/></svg>とし、<body>上部のスプライトを参照してください。カタログについてはcomponents.mdの§13を参照してください。コールアウト、doc-meta、topbar、本文のどこにも絵文字を使用しないでください。
9. アンカーリンクとクリップボードへのコピー機能は、JSによって自動で追加されます。手動で追加しないでください。H2/H3に適切なidを付け、コードは<pre><code>に入れてください。あとはテンプレートの起動スクリプトが処理します。
10. 幅の広い表は.table-wrapで囲んでください。詳細はcomponents.md §14bを参照してください。列が4つ以上ある表や、セルの内容が長い表には、モバイルでスクロールできるようラッパーが必要です。
11. 画像には<figure>と<figcaption>を使用し、内容を説明するaltを付けてください。 詳細はcomponents.md §14aを参照してください。

複数AI間の互換性

このスキルは、以下の環境で同じように動作するように設計されています。

• Claude Code — ~/.claude/skills/md2html/（このディレクトリ。シンボリックリンクまたはコピー）にインストールします。/md2html <file>で実行します。
• Codex CLI — SKILL.mdの内容を~/.codex/prompts/md2html.mdにコピーし、template.htmlとcomponents.mdを安定した絶対パスに置きます。必要に応じて、SKILL.md内のファイル参照を更新してください。/md2htmlで実行します。
• Antigravity — SKILL.mdをカスタムプロンプトまたはエージェント指示として追加し、エージェントがスキルフォルダーに対するRead/Writeツールへのアクセス権を持つことを確認してください。

外部依存関係はCDN経由のmermaidのみです（スキルの実行時ではなく、HTMLを開いたときに読み込まれます）。スキル自体の実行にnpm/pipのインストールは必要ありません。

エッジケース

• ソースに見出しがない場合 — コンテンツを<h2 id="content">Nội dung</h2>で囲み、空行と話題の変化から論理的な区切りを推測してください。
• ソースに既存のmermaidコードブロックがある場合 — そのまま維持し、キャプション付きの<figure class="diagram">で囲んでください。
• ソースにHTMLが埋め込まれている場合 — 安全であれば<div>内にそのまま渡し、安全でなければエスケープしてください。
• ソースが非常に短い（200語未満）場合 — TOCサイドバー（<aside class="toc">ブロック）を削除し、1列で表示してください。
• ソースが非常に長い（5000語超）場合 — 優先度の低いセクションは、デフォルトで<details>を使って折りたたんでください。
• 出力ファイルがすでに存在する場合 — 上書きしてください。ソースの.mdが正本であり、HTMLは再生成される成果物です。

アンチパターン

• ❌ Editを何度も小分けに呼び出してHTMLを生成する — 内容にずれが生じます。文字列全体を作成して、一度だけWriteしてください。
• ❌ <style>を使ってCSSを追加する — 代わりにtemplate.htmlを拡張し、その旨をユーザーに伝えてください。
• ❌ 固有名詞やコード識別子を翻訳する。
• ❌ 原文にない情報を加えて、ソースを「改善」する。
• ❌ Step 4の検証を実行せずに、成功したと報告する。