html-report

html-report

Markdown 本文を、Plotly / highlight.js / Mermaid / KaTeX / 生 HTML を内蔵した 1 枚の HTML レポートへ組み立てるスキル。

設計の要点 (なぜこの形か)

• 本文は最上部の <script type="text/markdown" id="content"> に入る。 この ブロックの中身はブラウザに実行・解釈されない生テキスト (script data) なので、 Markdown の <, &, コメント等が壊れず逐語的に保持される (<template> だと HTML パースされて壊れる)。人間も Claude もここだけ編集すればよい。
• ライブラリは末尾にまとめて配置。 <meta charset> を先頭に保ったまま本文を 上部に置けるので、編集対象がファイルの先頭に来て扱いやすい。巨大なライブラリ blob は末尾なので、編集時は先頭スライスだけ読めば済む。
• クライアントサイド描画。 ソース (=編集対象) と成果物が同一ファイル。ビルド工程は ライブラリ配置の 1 回だけで、本文修正に再ビルドは不要。

ワークフロー

1. 本文を Markdown で書く。 通常の Markdown + 生 HTML に加え、数式・コード・ Mermaid・Plotly が使える。各記法は references/authoring.md を参照。 examples/sample.md が全要素入りの実例。

2. 組み立てる。 スクリプトでテンプレートに流し込み、ライブラリを配置する:

   # CDN 参照版 (軽量・閲覧にネット必須。デフォルト)
   python "${CLAUDE_PLUGIN_ROOT}/skills/html-report/scripts/build_report.py" --content report.md --out report.html --title "タイトル"
   
   # 自己完結版 (ライブラリ + KaTeX フォントを同梱。オフライン共有用)
   python "${CLAUDE_PLUGIN_ROOT}/skills/html-report/scripts/build_report.py" --content report.md --out report.html --inline --title "タイトル"
   
   # 画像同梱 + ファイル添付 + 自己完結
   python "${CLAUDE_PLUGIN_ROOT}/skills/html-report/scripts/build_report.py" --content report.md --out report.html --inline \
     --attach data.csv fig.png
   
   # 構文チェックのみ (出力しない)
   python "${CLAUDE_PLUGIN_ROOT}/skills/html-report/scripts/build_report.py" --check --content report.md
   

   ${CLAUDE_PLUGIN_ROOT} はプラグインのルート (Claude Code が自動設定)。スクリプトは 依存ライブラリのない素の Python 3.10+ で動く (uv 環境なら uv run でもよい)。 --inline 時は CDN からライブラリを取得して ~/.cache/html-report-builder/ に キャッシュするため初回のみネットが要る (HTML_REPORT_VENDOR で保存先変更可)。 ビルド時に簡易 lint が走り、エラーがあれば中断する (--force で続行可)。

3. 確認する。 report.html をブラウザで開く。プレビュー手段があれば描画崩れ (グラフ・数式・図) を必ず目視確認する。

4. 以後の修正は本文だけ編集する。 report.html 先頭の <script type="text/markdown"> 内を直接 Edit する (Read は先頭スライスのみで よい)。ライブラリ部は触らない。再ビルド不要。

CDN 版 / 自己完結版の使い分け

• CDN 版 (default): ファイルが小さく編集しやすい。閲覧時にネット接続が要る。 作成・反復作業中はこちらが快適。

• 自己完結版 (--inline): ライブラリと KaTeX の woff2 フォントまで data URI で 埋め込むので、オフライン・メール添付・長期保管に強い。代わりに数 MB になる (Plotly が大半)。配布が目的なら最終的にこちらにする。

• CDN 版を後から自己完結版へ変換することもできる:

  python "${CLAUDE_PLUGIN_ROOT}/skills/html-report/scripts/build_report.py" --freeze report.html --out report.offline.html
  

ユーザーがオフライン/配布要件を明言していない場合は、デフォルト (CDN) で作成し、 「共有・オフライン保存するなら --inline で同梱版も作れる」と一言添えるとよい。

本文の書き方

特殊ブロック (Plotly / Mermaid / 数式 / コード) の具体的な記法と注意点は references/authoring.md にまとめてある。新しいレポートを書く前に一読すること。 要点だけ:

• 数式: $...$ / $$...$$
• コード: 言語付きフェンスドブロック ```python など
• Mermaid: ```mermaid ブロック
• Plotly: ```plotly ブロックに {"data":[...], "layout":{...}} の JSON
• 画像: ![alt](fig.png) でローカル画像を参照 → ビルド時に data URI 同梱 (matplotlib 等)
• 生 HTML はそのまま埋め込み可

追加機能

• 画像同梱: ローカル画像を指す ![](...) / <img> はビルド時に data URI 化され 単一 HTML に同梱される。Markdown は参照形式に変換し base64 を末尾へ退避するので 編集性を損なわない。matplotlib で図を保存して参照するのが定番。
• ファイル添付 (--attach FILE ...): 任意ファイルを base64 同梱し、末尾の 「添付ファイル」セクションから Blob ダウンロードできる。
• コピーボタン: 生成 HTML のタイトル横に「全コピー」、各見出し横に「見出し単位 コピー」が自動で付く (執筆側の対応は不要)。
• 構文チェック: ビルド時に Plotly JSON・コードフェンス・$$・ローカル画像存在・ HTML タグ開閉・</script> 混入を検査。--check で検証のみ、--force で続行。

注意点

• 本文中に文字列 </script> を入れると <script> ブロックが閉じてしまう。 スクリプトが自動退避するが、手編集で足す場合は <\/script> とエスケープする。
• ライブラリのバージョンは scripts/build_report.py 冒頭で固定。変更したい場合は そこの URL を編集する。