MacoTasu spec-page — 仕様書・説明書を HTML 1枚にまとめる
まず問う: HTML にする理由があるか
markdown で足りるなら markdown にする。 HTML を選ぶのは次のどれかが成立するときだけ。
- 構造を図で示したい — 依存関係・役割の分離・処理の流れなど、箇条書きでは伝わらないもの
- 一覧ではなく読み物にしたい — 上から読んで理解が組み上がる順序が要る
- 体裁が意味を持つ — 識別子・状態・分類を書体や色で区別したい
「見栄えを良くしたい」は理由にならない。その場合 markdown のままのほうが速く、腐りにくい。
書く前に1文で決める
このページの主張は何か。 収録物の一覧ではなく、読者に1つだけ持ち帰ってほしいことを1文にする。 それが決まらないうちは書き始めない。主張が決まると、図に描くべきものと、削るべき節が決まる。
併せて読者を決める。半年後の自分か、初めて触る他人か、レビューする同僚か。 これで前提の書き方（何を説明し、何を省くか）が変わる。
構成の型
| 節 | 役割 | 必須 |
|---|---|---|
| マストヘッド | 名前・主張の1文・前書き（何で、何のためか） | ✅ |
| 本体 | 対象に応じた節。一覧・手順・比較など | ✅ |
| 構造の図 | 主張を1枚で示す。HTML を選んだ理由がここに現れる | 推奨 |
| 決定の記録 | なぜそう決めたか。結論ではなく理由を残す | ✅ |
決定の記録が、この形式の核
半年後に腐るのは結論ではなく理由。「なぜ2つに分けたのか」「なぜこの置き場なのか」が失われると、 同じ検討をやり直すか、理由のない制約として温存される。次の条件に当てはまる決定だけを残す。
- 後から見て不自然に見えるもの（合理的な理由があるのに、結果だけ見ると遠回りに見える）
- 一度別の結論を出してから変えたもの。変えた理由ごと書く
- やらないと決めたもの。やらない理由は特に失われやすい
逆に、自明な決定は書かない。全部書くと埋もれて、結局どれも読まれない。
体裁の規約
- 識別子は等幅に固定する — プラグイン名・ファイル名・コマンド・設定キー。名前が識別子であることを
書体で示す。本文中の強調（
<strong>）とは役割が違うので混ぜない - 罫線と余白で律動を作る — カードを並べない。文書は読み物であって、ダッシュボードではない
- 型の階層を決めて守る — 見出し・本文・注記・データの4役に、それぞれ書体と級数を割り当てる
- 構造が情報を担うときだけ構造を足す — 番号付きマーカーは、本当に順序が意味を持つときだけ。 そうでなければただの装飾になる
- 色は意味に割り当てる — 状態（成功・警告・失敗）に色を使うなら、アクセント色とは別系統にする
公開前チェック（必須）
同梱の reference/publish-checklist.md を実行する。
読んで想像するのではなく、実際にブラウザで開いて確かめる。
とくに <meta charset="utf-8"> の欠落は、プレビュー環境では露見せず配信環境で初めて文字化けとして出る。
構造検査だけでは捕まらない。
配信の2経路
A. Artifact（試作・私的共有）
設定ゼロで、既定はプライベート。まずここで見た目を確定させるのが安い。 単発の設計文書・調査報告は、これで完結してよい。
制約: リポジトリと紐づかない。git で版管理されない。公開ドキュメントの正式な置き場には向かない。
B. リポジトリの docs/ ＋ GitHub Pages（版管理・公開）
リポジトリの説明書はこちら。 コードと同じ PR でドキュメントも直せるので、実装とページがズレない。
# public リポジトリなら無料・ビルド不要
gh api -X POST repos/<owner>/<repo>/pages \
-f "source[branch]=main" -f "source[path]=/docs"
- 配信元は
/（リポジトリルート）か/docsの2択。任意のフォルダは選べない。ルートにindex.htmlを置くのはノイズなので/docs一択 gh-pages別ブランチにしない — ドキュメントの更新が別コミットになると「実装を変えたのに ページが古い」という腐り方を招く。同じ PR で直せることが最大の利点docs/.nojekyllを置く — Jekyll 処理をスキップする。_始まりのファイルが無視される、{{ }}や{% %}が展開される、といった原因の見えにくい壊れ方を恒久的に塞げる- README の冒頭からリンクする — リポジトリの入口は markdown しかレンダリングされないので、 README は残る。HTML はその補助
両方を使う場合、同じファイルを指す。 Artifact 用と Pages 用で別ファイルを持つと必ず片方が腐る。
docs/index.html を書いて、それを Artifact として publish し、良ければそのまま Pages に載せる。
閲覧を限定したいとき
個人アカウントの GitHub Pages に閲覧制限はかけられない（Organization ＋ Enterprise Cloud のみ）。 public リポジトリなら Pages も公開される。限定したいなら Artifact（既定プライベート）を使う。
作業の順序
- 主張を1文で決める。読者を決める
- 構成を決める（上の型）。図に描くものを決める
- 書く。実データ・実名で書く（プレースホルダで組まない）
reference/publish-checklist.mdを実行する- Artifact として publish し、実際に開いて確認する
- リポジトリのドキュメントなら
docs/に置き、.nojekyllを添えて Pages を有効化、README からリンク