全体構成¶

各リポジトリの docs/ だけを、build 直前に docs-hub/docs/<リポジトリ名>/ へ一時コピーする。そのあと zensical build が HTML にする。

finance-manager/docs/  ─┐
pve-infra/docs/        ─┤
home-kitchen/docs/     ─┼─→ docs-hub/docs/<name>/  → zensical build → site/
（今後のリポジトリ）   ─┘

ハブの Git には、各リポジトリの本文を残さない。 .gitignore で生成物を除外し、正本は常にソース側にある。

ローカル¶

~/git/finance-manager/docs
~/git/pve-infra/docs
~/git/home/docs
        │
        │  scripts/aggregate.sh
        ▼
docs-hub/docs/finance-manager/
docs-hub/docs/pve-infra/
docs-hub/docs/home-kitchen/
        │
        │  zensical build
        ▼
docs-hub/site/

PAT は使わない。隣の clone を cp するだけである。

CI（GitHub Actions）¶

PAT (DOCS_READ_TOKEN)
  → finance-manager / pve-infra / home-kitchen を _sources/ に checkout
  → 同じ aggregate.sh（パスは環境変数で差し替え）
  → zensical build
  → wrangler で Cloudflare Pages へデプロイ

ハブに常駐するもの¶

パス	内容
`docs/index.md`	サイト入口
`docs/hub/`	この運用ドキュメント（Git 管理）
`zensical.toml`	サイト設定（ナビはフォルダから自動生成）
`docs/stylesheets/layout.css`	コンテンツ横幅
`docs/stylesheets/mermaid.css`	図の虫眼鏡ボタン
`docs/javascripts/mermaid-zoom.js`	図の拡大ビュー
`scripts/aggregate.sh`	コピー処理
`.github/workflows/build.yml`	集約、ビルド、デプロイ

docs/finance-manager/ と docs/pve-infra/ と docs/home-kitchen/ は生成物なので、Git に入れない。

言語指定が mermaid のフェンスは、ハブの SuperFences に custom_fences を置いて初めて図になる。未設定だとコードブロック（コピー、添付）のままである。設定は Zensical の Diagrams どおりである。

図の右上に、コードコピーと同じ系統の虫眼鏡を置く。 Zensical 本体に拡大はない。

ナビについて¶

zensical.toml にページ一覧（nav）は書かない。

明示すると、ソース側でファイルを移したあとハブの toml を直し忘れると 404 になる。ナビは集約後の docs/ フォルダ構成から Zensical が自動生成する。

ソースリポジトリでやることは次のとおりである。

docs/ のファイルを追加、移動する
同じリポジトリ内の相対リンクを直す
push する（ハブの toml は触らない）

並び順はフォルダ名、ファイル名順である。固定したいときは 01-overview のようなプレフィックスを使う。