🏛️ SSOT Guide
← プロジェクト紹介

09 ガイドサイト構築 — このサイトのしくみ

Markdown → モバイル対応HTMLへの変換パイプラインと品質保証の仕組みを解説する

アーキテクチャ概要

source/*.md          ← 章ごとのMarkdownソース
    ↓ convert.py
docs/chapters/*.html ← 生成済みHTML（GitHub Pages公開）
docs/index.html      ← トップページ
docs/assets/         ← style.css / script.js

convert.py 1ファイルがビルド全体を担当する。外部CMSやSSGに依存せず、Pythonの標準的なライブラリのみで動作する。

convert.py の主要関数

関数 役割
build_chapter_map() source/ をスキャンして章リストを構築（手動定義 + 自動検出）
filter_sections(text) 不要セクション・パーソナル情報を除去
convert_md_to_html(md) Markdown → HTML（markdown-it-py 使用）
inject_mermaid(html, filename) Mermaid図を指定位置に挿入
rewrite_links(html, chapter_map) .md リンクを .html に書き換え
enhance_html(html) テーブルラップ・callout変換などの装飾
main() 全章を変換して docs/ に出力

章の自動検出

CHAPTER_MAP に登録されていないMarkdownファイルを自動スキャンして追加する。
フロントマターに title / icon / desc を書くと反映される:

---
title: 新しい章
icon: 🔧
desc: この章の説明
---

テストスイート

test_convert.py（9クラス・45テスト）で変換パイプラインを自動検証する。

python3 -m pytest test_convert.py -v

テストクラス一覧

クラス テスト数 カバー内容
TestFilenameToSlug 5 ファイル名→slug変換（ASCII・日本語・連続ハイフン）
TestExtractFromH1 5 H1からタイトル・説明を抽出
TestFilterSections 4 セクション除去・不要テキストの清掃
TestConvertMdToHtml 4 見出し・コード・テーブル・太字
TestMermaidInjection 3 図なし・未知ファイル・図あり時
TestRewriteLinks 7 MD→HTML変換・アンカー・壊れたリンク
TestEnhanceHtml 5 テーブルラップ・callout 4種
TestBuildChapterMap 4 自動スキャン・手動定義保持・キー検証
TestBuildIntegrity 8 ビルド後HTML構造・OGP・壊れたリンクゼロ確認

新機能を追加する時の手順

  1. source/ に Markdown を書く
  2. convert.py に関数・ロジックを追加
  3. test_convert.py に対応テストを追加
  4. python3 -m pytest test_convert.py -q で確認
  5. python3 convert.py でビルド
  6. git add -A && git commit && git push

GitHub Pages 公開

リポジトリの Settings → Pages → Source: main ブランチ /docs フォルダ に設定する。

git push するだけで自動公開される（ビルドはローカルで実行してから push）。

公開URL: https://<username>.github.io/<repo>/

CSS変数とテーマ

docs/assets/style.css はCSS変数でライト/ダークモードを管理する。

:root {
    --bg: #f0f2ff;
    --bg-card: #ffffff;
    --text: #1a1f3a;
    --accent: #5b4cf5;
    /* ... */
}

[data-theme="dark"] {
    --bg: #0d0f1e;
    --text: #e2e8f0;
    /* ... */
}

callout系の変数は必ず定義すること（未定義の場合、ダークモードで視認不能になる）:

/* ライト側でも定義が必要 */
--callout-info-bg: var(--blue-bg);
--callout-warn-bg: var(--amber-bg);
--callout-tip-bg: var(--green-bg);
--callout-danger-bg: var(--red-bg);

新しいカラー変数を追加する時は :root と [data-theme="dark"] の両方に追加する。

Mermaid図の追加

convert.py の MERMAID_DIAGRAMS に定義する:

MERMAID_DIAGRAMS = {
    "03_Claude-Code統合.md": [
        ("## アーキテクチャ", """
graph TD
    A[CLAUDE.md] --> B[Claude Code]
    B --> C[Hooks]
    B --> D[Memory]
"""),
    ],
}

指定した見出しの直前に図が挿入される。

バージョン管理

VERSION ファイルでビルド番号を管理する。ビルドのたびにマイナーバージョンが自動インクリメントされ、フッターに表示される。

VERSION ファイル内容: 1.10
表示: v1.10 · 2026.05.31

仕組み

# convert.py の get_build_info()
def get_build_info() -> tuple[str, str]:
    current = VERSION_FILE.read_text().strip()   # "1.10"
    new_version = bump_version(current)           # "1.11"
    VERSION_FILE.write_text(new_version + "\n")
    today = date.today().strftime("%Y.%m.%d")
    return new_version, today

python3 convert.py を実行するたびに VERSION が上がる。

テスト時の注意

テストが main() を呼ぶたびにバージョンが上がってしまう。unittest.mock.patch で固定する:

@pytest.fixture(autouse=True)
def _build(self):
    import convert
    with patch.object(convert, "get_build_info", return_value=("TEST", "2026.01.01")):
        convert.main()

初期化

新規サイトを立ち上げた時は VERSION ファイルを作成する:

echo "1.0" > VERSION

既存ガイドのパイプライン移行

手書きHTML単体のガイドを convert.py パイプラインへ移行する手順。guide-builder スキルの新規作成ではなく、既存公開ガイドの載せ替え。

手順

  1. 既存ガイド（ssot-guide等）から convert.py / test_convert.py / VERSION / docs/assets/ をコピー
  2. CHAPTER_MAP を新ガイドの章構成に書き換え
  3. CHAPTER_TEMPLATE / INDEX_TEMPLATE のサイト名・URL・OGP・favicon・hero・features をガイド向けにカスタマイズ
  4. source/*.md に章Markdownを振り分け（旧HTMLの内容を章ごとに分割）
  5. pytest → convert.py ビルド → GitHub Pages公開

よくあるズレと調整

ズレ 調整
移行先リポが既に公開済み git init / gh repo create は不要・push のみ
コピー元 convert.py が更新されている セキュリティ修正（XSS/ReDoS等）取り込み済みか確認
Pages公開方式の競合 Actions workflow（path: .）と branch /docs は排他。branch 方式にするなら該当 workflow を削除
build-deploy.yml の cache: 'pip' requirements.txt / pyproject.toml 未配置リポだと setup-python がエラーになる。該当行を削除（dev-textbook 実例）
test_convert.py の slug 名 rewrite_links のアンカー付きリンクテスト等が旧 CHAPTER_MAP の slug に依存。新章の slug に書き換え
旧URLからの移行 旧リポの index.html を meta refresh リダイレクトページ化

テストの修正

test_convert.py が旧 CHAPTER_MAP の具体ファイル名に依存している場合がある。rewrite_links のアンカー付きリンクテスト等は新 CHAPTER_MAP のファイル名・slug に合わせて書き換える。

参考実装