設計書HTMLビューア 設計書

1. 目的

設計書はMarkdownで書き、Markdownを正本のまま残しつつ、すべての設計書をブラウザで読める形で公開する。

理由:

• 設計書は共有相手（社内・外部パートナー）がいる。GitHubのMD表示ではなくURL1本で渡したい
• 一方でMDをやめてHTML手書きにすると、資料1本ごとにHTMLを書く手間とトークンが毎回かかる
• 変換を自動化すれば、2本目以降のHTML化コストはゼロになる

2. 方針

docs/superpowers/specs/*.md を変換スクリプトでHTMLに変換し、specs/ 配下に出力する。

• 正本はMarkdown。HTMLは生成物であり、直接編集しない
• 生成物もgitにコミットする（Cloudflare Pagesがビルドを実行しない構成のため）
• 変換は Node標準機能のみで行い、外部パッケージに依存しない

外部パッケージを使わない理由: 変換対象は自分たちが書くMarkdownで、使う記法が限られているため。将来より複雑な記法が必要になった場合は、markedなどのライブラリに差し替える。

3. 入出力

一覧ページには、各設計書のタイトル・作成日・対象（MD冒頭の見出しとメタ行から抽出）を新しい順に並べる。

4. 対応するMarkdown記法

今書いている設計書で使う範囲に限定する。

• 見出し（# 〜 ####）
• 段落、強調（**）、インラインコード
• 箇条書き（-）、番号付きリスト、ネスト1段
• 表（ヘッダ行＋区切り行＋データ行、セル内の強調とインラインコード）
• 引用（>）
• 水平線（---）
• リンク（[text](url)）

未対応の記法が入力に現れた場合は、その行をそのまま段落として出力する（変換を失敗させない）。

5. 出力HTMLの要件

• 自己完結: 外部CDN・外部フォントを読み込まない。CSSはインライン
• <meta name="robots" content="noindex"> を入れる
• レスポンシブ（スマホで読める）
• 印刷用CSS（@media print）を入れ、ブラウザの「PDFに保存」でA4に収まるようにする。表とセクションが途中で切れないよう break-inside: avoid を指定
• ページ上部に一覧ページへ戻るリンクを置く
• HTMLエスケープを行い、Markdown由来のテキストがタグとして解釈されないようにする

6. 運用手順

1. docs/superpowers/specs/ にMarkdownで設計書を書く
2. node tools/build-specs.mjs を実行する
3. commit & push → https://originals-docs.pages.dev/specs/ に反映

将来、Cloudflare Pagesのビルドコマンドに node tools/build-specs.mjs を設定すれば、手順2は不要になる（ダッシュボードでの設定変更が必要なため、今回は行わない）。

7. スコープ外

• Markdownの完全なCommonMark対応
• 設計書の閲覧制限（現状は他の資料と同じくURL非公開のみ。社外秘扱いが必要になった時点でCloudflare Accessを検討）
• 図表の自動生成（図が必要な設計書は個別にHTMLを手書きする）