mkdocs-site-bootstrap

mkdocs-site-bootstrap

リポジトリ用の MkDocs Material ドキュメントサイトをセットアップし、（任意で）デプロイした後、ユーザーがページを追加していくのを継続的に支援します。

このスキルは同意を得てから実行します。ユーザーの設定を .skills/preferences.yaml に記録し、明示的な依頼がない限り既存のコンテンツや設定を移行しません。移行コマンドはデフォルトでは監査のみを行い、--apply を指定した場合に限り書き込みます。ユーザーが考えを変えた場合は、 scripts/check-preferences.sh --reset mkdocs_site_bootstrap を実行すると、記録された判断が消去され、次回の実行時に最初から確認できます。

実行するタイミング

• ユーザーが「ドキュメントをセットアップして」「ドキュメントサイトを作成して」「ドキュメントサイトを追加して」「GitHub Pages にドキュメントを公開して」と依頼した場合
• ユーザーが Markdown のメモや docs/ ディレクトリを持っていて、閲覧可能にしたい場合
• ユーザーが daviddwlee84/agent-skills リポジトリと同じドキュメントスタックを新しいプロジェクトに適用したい場合
• ユーザーが LLM に適したドキュメントサイト（llms.txt、copy-to-LLM）を希望している場合
• ユーザーが「バイリンガルのドキュメント」「雙語 docs」「i18n」「多言語」「繁体字中国語を追加」「zh-TW を追加」「ドキュメントを翻訳」、または既存のサイトに英語以外の言語を追加してほしいと依頼した場合 → 手順 7 に進みます
• llms.txt / llms-full.txt が空になった、1 つのロケールしか含まれない、または i18n の追加によって厳格なビルドが失敗したとユーザーから報告された場合 → 手順 8 に進みます

実行しないタイミング

• ユーザーがドキュメントファイルを 1 つ書きたいだけの場合 → サイト全体をスキャフォールドしないでください
• ユーザーが明示的にオプトアウトしている場合（preferences.yaml に enabled: false と記載）→ ユーザーがその判断を取り消そうとしている場合を除き、対応を見送ってください
• ユーザーがスキルの評価やベンチマークを希望している場合 → skill-creator を使用してください
• ユーザーが新しいエージェントスキルの作成を希望している場合 → skill-author を使用してください

ワークフロー

1. 最初に設定を確認する

作業を始める前に、このリポジトリにすでに判断が記録されているか確認します。

bash skills/local/mkdocs-site-bootstrap/scripts/check-preferences.sh \
  --get mkdocs_site_bootstrap

考えられる状態は次のとおりです。

状態	意味	対応
ファイルが存在しない、またはキーがない	まだ確認していません	手順 2（ヒアリング）に進みます
enabled: true, pages_deployed: true	サイトは公開中です	手順 6（継続的な支援）に進みます
enabled: true, pages_deployed: false	スキャフォールド済みですが、未デプロイです	手順 5（デプロイ）に進みます
enabled: false	ユーザーはオプトアウトしています	判断を取り消すか確認してから、--reset を実行し、再度実行します

2. ヒアリング（判断が記録されていない場合のみ）

ユーザーに明確に尋ねます。

1. 「このプロジェクト用に MkDocs Material ドキュメントサイトを作成しますか？ （はい / いいえ / 考えさせてください）」
2. はいの場合：「main へのプッシュ時に GitHub Pages へ自動デプロイしますか？ （はい / いいえ — 手動でデプロイします）」

セッションが中断されても回答が失われないよう、両方の回答をすぐに記録します。

bash skills/local/mkdocs-site-bootstrap/scripts/check-preferences.sh \
  --set mkdocs_site_bootstrap.enabled=true \
  --set mkdocs_site_bootstrap.stack=mkdocs-material \
  --set mkdocs_site_bootstrap.auto_deploy=true

ユーザーが「いいえ」と答えた場合は、enabled: false を記録して終了します。今後の実行時に何度も尋ねないでください。

3. 既存のドキュメントを検出する（同意確認）

スキャフォールドする前に、対象のリポジトリをスキャンします。詳しい判断フローは references/existing-docs-handling.md を参照してください。概要は次のとおりです。

• mkdocs.yml がすでに存在する場合 → 「 に mkdocs サイトがすでに存在するようです。上書きしません」と報告して終了します。
• docs/ が存在し、中身が空でない場合 → ファイル一覧を表示し、次のいずれかを選ぶようユーザーに尋ねます。 (a) スキップ — ドキュメントには手を加えず、ファイルシステムによる自動ナビゲーションのため nav を省略して mkdocs.yml のみ作成します。 (b) 包み込む — Markdown のパスをそのまま含め、アルファベット順の明示的なナビゲーションを設定した mkdocs.yml を作成します。 (c) 手動 — 先に整理してから再実行します。
• どちらも存在しない場合 → 安全に最初からスキャフォールドできます。

判断を mkdocs_site_bootstrap.existing_docs_decision に記録します。

4. スキャフォールド

init-docs-site.sh を実行します。このスクリプトは mkdocs.yml、 pyproject.toml（[project.optional-dependencies] docs = […] を含む）、 docs/ のひな形、.github/workflows/docs.yml、管理対象の scripts/build-docs-site.py ヘルパー、および copy-to-llm 用のスタブアセットを 作成します（既存ファイルがある場合は上書きせずに終了します）。また、 ビルド出力ディレクトリである /site/ を .gitignore に追記し、生成されたサイトが コミットされないようにします。--social を指定した場合は /.cache/ も追記します。

bash skills/local/mkdocs-site-bootstrap/scripts/init-docs-site.sh \
  --site-name "My Project" \
  --repo-slug owner/repo \
  --site-url https://owner.github.io/repo/

まず --dry-run でプレビューしてください。スクリプトは --force を指定しない限り 既存ファイルを常に保持し、リポジトリ外への書き込みを避けるため、既存の docs/ ツリー内にシンボリックリンクがある場合は処理を拒否します。skip および wrap モードでは、ビルドフックが生成アセットを docs/ 内に書き込む copy-to-llm を省略します。ユーザーは、生成ファイルの配置場所を決めた後に、 このプラグインを個別に有効にできます。

OG／Twitter プレビューカードを有効にするには --social を指定します（Gotchas →「ソーシャルカードはオプトインです」を参照）。リッチリンクプレビューが必要で、 Cairo／Pango のシステム依存関係を受け入れられる場合を除き、指定しないでください。 通常のスキャフォールドは依存関係なしでビルドできます。

スキャフォールドの作成後、完全な厳格モードの成果物をビルドします。

uv sync --extra docs
uv run python scripts/build-docs-site.py

llmstxt を維持する多言語サイトでは、言語ごとに分離した厳格モードの処理を 2 回実行します。まずデフォルト言語の LLM 出力、次に多言語 HTML サイト全体を ビルドします。mkdocs.yml では llmstxt がデフォルトで無効になっているため、 uv run mkdocs build --strict を直接実行しても安全な HTML のみのプレビューになります。 サイトの要件に /llms.txt が含まれる場合は、そのプレビューをデプロイしないでください。

5. Pages を有効にして初回デプロイを実行する（同意ゲート）

この処理では GitHub API（gh api -X POST .../pages -f build_type=workflow）を呼び出し、 その後ワークフローを実行します。必ず事前にユーザーに確認してください。 実行する API 呼び出しの内容と、影響を受けるリポジトリを正確に伝えてください。 明示的な承認がある場合にのみ続行します。

bash skills/local/mkdocs-site-bootstrap/scripts/enable-pages.sh \
  --repo owner/repo

フラグ：

• --dry-run — gh の呼び出しを実行せずに表示します
• --no-trigger — Pages を有効にしますが、ワークフローはまだ実行しません

成功したら、設定に pages_deployed=true と pages_enabled_at=$(date +%F) を設定します。

6. 継続的な作業：ドキュメントページを追加する

ユーザーが新しいドキュメントを追加したい場合は、mkdocs.yml を直接編集せず、 ヘルパーを使用します。

bash skills/local/mkdocs-site-bootstrap/scripts/add-docs-page.sh \
  --section workflows \
  --title "My new workflow" \
  --slug my-new-workflow

ページテンプレートから docs/<section>/<slug>.md を作成し、該当するセクション見出しの下に mkdocs.yml のナビゲーション項目を挿入します。冪等性があるため、同じスラッグで 再実行しても何も変更されません。

.skills/preferences.yaml の mkdocs_site_bootstrap.languages に追加の言語が 設定されている場合、add-docs-page.sh はデフォルト以外のすべての言語について *.<LANG>.md のスタブも生成し、用語規則の注意書きをあらかじめ挿入します。 特定の言語の翻訳だけを追加し、デフォルト言語のファイルを再作成しない場合は、 --lang LANG を使用します。

7. オプション：英語以外の言語を追加する

このスキルは、mkdocs-static-i18n プラグインを使用したバイリンガル／多言語サイトに対応しています （サフィックス形式：index.md + index.zh-TW.md）。 この手順は任意で、初期セットアップとは切り離されています。

実行条件：ユーザーが「バイリンガルドキュメント」、「雙語 docs」、「add zh-TW」、「i18n」、 「繁体字中国語を追加」、「ドキュメントを翻訳」などを依頼した場合。

まず references/i18n-guide.md を読んでください。非英語ページで執筆者が守る必要のある 用語保持ルール（初出時に「中文 (English original)」形式を使うこと。独自の訳語を作らないこと）が説明されています。

次を実行します：

bash skills/local/mkdocs-site-bootstrap/scripts/add-language.sh \
  --lang zh-TW

これにより、i18n プラグインが mkdocs.yml に挿入され、既存のすべてのページの兄弟ファイルとして *.zh-TW.md の スタブが作成されます（用語に関する注意書きがあらかじめ挿入されます）。また、管理対象の厳格なビルドヘルパーをインストールして設定し、 2 パスビルドに必要なプラグインガードを有効にし、pyproject.toml の mkdocs-static-i18n のコメントアウトを解除し、 .skills/preferences.yaml に選択内容を記録します。冪等性があり、同じ --lang を指定して再実行しても何も変更されません。

--remove-llmstxt は、引き続き明示的なオプトアウトとして使用できます。旧 --drop-strict フラグは、 strict を削除しても破損した出力が修正されなかったため、非推奨の無操作フラグです。 --keep-llmstxt は、現在のデフォルトを指す非推奨の別名として使用できます。

実行後、依存関係を再同期してビルドします：

uv sync --extra docs
uv run python scripts/build-docs-site.py

スクリプトの完了後 — 翻訳は別の手順です

add-language.sh が作成するのは構造上のプレースホルダーのみです。各 *.<LANG>.md スタブには、用語に関する注意書きと「Translation pending」という警告が含まれます。LLM による翻訳は「独自の訳語を作らない」という用語ルールに 日常的に違反するため（たとえば、embedding に定訳がないのに「嵌入」／「向量」／「内嵌」といった訳語を作り出すなど）、 スクリプトが本文を自動翻訳することはありません。

スタブが作成されたら、今すぐ翻訳するかどうかをユーザーに明示的に尋ねてください — 勝手に翻訳を進めてはいけません。たとえば、次のように尋ねます：

「スタブを作成しました。本文をページごとに翻訳しましょうか？ 1 回につき 4～6 ページを翻訳し、 バッチの合間に mkdocs build を実行して検証します。また、用語ルール（初出時に英語の原語を併記し、 独自の訳語を作らないこと）に従います。」

明示的に承諾された場合のみ進めてください。ユーザーが保留にする場合は、スタブをそのまま残してください — これらはすでに有効なページであり、ビルドも成功します。

翻訳時には、トップレベルのセクション見出しに対する nav_translations を mkdocs.yml に記入することも提案してください （references/i18n-guide.md の §nav_translations を参照）。 これはページ本文の翻訳とは独立しており、ユーザーはどちらか一方だけを希望する場合があります。

8. 以前の i18n + llmstxt スキャフォールドを修復する

インストール済みスキルを更新しても、新しいツールがダウンロードされるだけで、下流プロジェクトが 書き換えられることはありません。既存のサイトを移行する前に references/i18n-llmstxt-migration.md を読み、 まず監査を実行してください：

npx skills@latest update mkdocs-site-bootstrap --project --yes
bash .agents/skills/mkdocs-site-bootstrap/scripts/migrate-i18n-llmstxt.sh \
  --target-dir . --json

終了コード 10 は、旧来の該当する構成が検出されたことを意味します（ドライランのプレビューを含みます）。 --apply --dry-run で保守的なパッチをプレビューしてから、--apply --verify を実行してください。 この移行では、スキャフォールドが管理するものと認識できる構成のみをパッチします。カスタムの docs_dir、プラグインガード、CI、 Makefile、または外部のビルドヘルパーは上書きされず、明示的な手動対応事項になります。 ローカライズされたソース内の安全でない相対 llms／サイドカーリンクも個別に報告されるため、 site_url ベースの URL に手動で置き換えてください。

利用可能なスクリプト

• scripts/check-preferences.sh — .skills/preferences.yaml の読み取り、設定、またはリセットを行います。常に安全に実行できます。
  • フラグ：--get KEY、--set KEY=VALUE（繰り返し指定可能）、--reset NAMESPACE、 --list、--dry-run、--json。
• scripts/init-docs-site.sh — サイトのファイル一式を作成します。
  • フラグ：--site-name、--repo-slug、--site-url、--existing skip|wrap、 --no-workflow、--no-skeleton、--social、--dry-run、--force。
  • .gitignore に常に /site/（mkdocs build の出力ディレクトリ）を追加します。冪等に実行できます。
  • --social を指定すると、OG/Twitter カードを有効にします。テンプレート内の __SOCIAL_*__ マーカーを assets/social/ 内のブロックで展開し、.gitignore に /.cache/ を追加します。 デフォルトでは無効であり、スキャフォールドに Cairo/Pango を必要としません。
• プロジェクトローカルの scripts/build-docs-site.py — 正規の厳格な本番ビルドヘルパーです。 assets/build-docs-site.py から各スキャフォールドにコピーされます。 単一言語サイトでは1回のパスでビルドします。llmstxt を使用する多言語サイトでは、 デフォルト言語の LLM 出力を完全な HTML ビルドから分離し、統合済みの成果物を検証してから、 すべてのチェックが成功した場合に限り site/ を置き換えます。JSON は標準出力に、 ビルド診断は標準エラー出力に書き込みます。
  • フラグ：--target-dir DIR、--config-file FILE、--site-dir DIR、 --dry-run、--keep-temp。
  • 終了コード：0 成功、2 入力が無効または不足、3 MkDocs の失敗、 4 生成された出力の検証失敗。
• scripts/enable-pages.sh — gh api 経由で Pages を有効にし、初回デプロイを開始します。 事前に gh auth status が成功している必要があります。
  • フラグ：--repo OWNER/REPO、--no-trigger、--dry-run。
• scripts/add-docs-page.sh — 新しいページを作成し、明示的なナビゲーションがある場合は更新して、 llmstxt.sections と同期させます。自動ナビゲーション（nav が省略されている場合）では、 _root ページは部分的な明示ナビゲーションを作成せず、引き続きファイルシステムから検出されます。 名前付きの --section は既存のセクションである必要があり、ページを書き込む前に検証されます。 複数の言語が設定されている場合は、デフォルト以外の各言語について *.<LANG>.md スタブも書き込みます。
  • フラグ：--section、--title、--slug、--template PATH、--lang LANG （単一言語のスタブのみ）、--dry-run、--force。
• scripts/add-language.sh — 既存のサイトにデフォルト以外の言語を追加します。 plugins.i18n を挿入し、用語に関するアドモニションを含む *.<LANG>.md スタブを作成し、 設定を更新して、静的 i18n の依存関係のコメントを解除し、管理対象の厳格なビルドパスを設定します。 デフォルトでは、デフォルト言語の mkdocs-llmstxt 出力を維持します。冪等に実行できます。
  • フラグ：--lang LANG（必須）、--name NAME、--default-lang LANG、 --target-dir DIR、--no-stubs、--remove-llmstxt、非推奨の --drop-strict / --keep-llmstxt、--dry-run、--force。
  • 終了コード 11 は、言語は追加されたものの、カスタムの下流構成には移行ガイドに記載された手動操作が まだ必要であることを示します。
• scripts/migrate-i18n-llmstxt.sh — このスキルの旧バージョンで作成された下流サイトを監査するか、 慎重に移行します。デフォルトでは監査のみ行い、書き込みには --apply が必要です。 JSON は標準出力に、診断は標準エラー出力に書き込みます。置き換え前に候補をステージングして検証し、 冪等に実行でき、外部のビルドヘルパーを上書きすることはありません。
  • フラグ：--target-dir DIR、--apply、--dry-run、--verify、--json。
  • 終了コード：0 安全／移行済み、10 監査／ドライランで影響を受ける旧設定を検出、 11 手動操作が残っている、12 厳格な検証に失敗。

リファレンスファイル

• references/preferences-schema.md — .skills/preferences.yaml のスキーマと、スキル間で共有する際の規約です。設定キーを初めて扱う際は、必ずお読みください。
• references/existing-docs-handling.md — ユーザーがすでに作成している docs/ の内容を予期せぬ変更なく扱うための、詳細な判断フローです。新規セットアップのたびに、手順 3 の前にお読みください。
• references/docs-stack-recipe.md — スタックのレシピ全文（mkdocs.yml、pyproject.toml、ワークフロー、リンク規則）です。ユーザーから「このスタックの具体的な内容は？」と質問された場合や、一部を手動で適用したい場合に役立ちます。
• references/i18n-guide.md — mkdocs-static-i18n を使ったバイリンガル／多言語ドキュメントのセットアップです。add-language.sh を実行する前にお読みください。zh-TW ページで「英語の原文を保持する」という用語規則の全文も記載しています。
• references/i18n-llmstxt-migration.md — 移行の監査、適用、検証ガイド、終了コードの仕様、自動パッチの範囲、手動での代替手順です。既存の i18n + llmstxt サイトを修復またはアップグレードする前にお読みください。
• references/mkdocs-2-and-zensical.md — スタックで mkdocs<2 と mkdocs-material<10 を固定している理由です。MkDocs 2.0 でのプラグイン廃止の状況、Material チームによる後継の Zensical、上限を引き上げる基準について記載しています。ユーザーから MkDocs のアップグレードや、ドキュメントのビルドが 1.x 系である理由について質問された場合はお読みください。

同梱アセット

スクリプトがコピーするテンプレートです。ユーザーのリポジトリではなく、ここで編集してください。

• assets/mkdocs.yml.template — Material テーマ、環境変数で制御される llmstxt、copy-to-llm、多言語対応の docs_dir、pymdownx.snippets が含まれます。{{SITE_NAME}}、{{REPO_SLUG}}、{{SITE_URL}} を使用してパラメーター化されています。__SOCIAL_*__ マーカー行が含まれており、init-docs-site.sh が展開（--social 指定時）または削除します。
• assets/pyproject.toml.template — 最小限の [project] ブロックと、ドキュメント用のオプション依存関係グループです。__SOCIAL_IMAGING__ マーカーが含まれています。
• assets/build-docs-site.py — 管理対象の 2 パスヘルパーです。下流プロジェクトの scripts/build-docs-site.py にコピーされます。移行ツールがユーザー所有のスクリプトと区別できるよう、管理対象マーカーをそのまま保持してください。
• assets/docs-workflow.yml.template — パスフィルター、uv のセットアップ、管理対象の厳格なビルドヘルパー、Pages のデプロイを含む .github/workflows/docs.yml です。Cairo/Pango とカードキャッシュの手順に使用する __SOCIAL_CI__ マーカーが含まれています。
• assets/social/ — init-docs-site.sh --social の指定時に、__SOCIAL_*__ マーカーの位置へ挿入されるスニペットです。mkdocs-plugin.yml（social プラグインのブロック）、pyproject-dep.txt（mkdocs-material[imaging]）、ci-steps.yml（Cairo/Pango のインストールと .cache/plugin/social キャッシュ）が含まれています。挿入位置に合わせたインデントが設定されているため、インデントを変更しないでください。
• assets/docs-skeleton/ — index.md、getting-started.md、_snippets/ の例、およびこのリポジトリからコピーされる assets/copy-to-llm/ の JS+CSS ファイルです。
• assets/page.md.template — add-docs-page.sh で使用します。
• assets/translation-stub.md.template — add-language.sh と add-docs-page.sh が、デフォルト以外の言語のページに使用するスタブです。用語規則についての注記の全文が含まれています。
• assets/i18n-plugin.yml.snippet — mkdocs-static-i18n プラグインの YAML ブロックの参照用です（references/i18n-guide.md で使用。スクリプトは yq を使って同等のブロックを作成します）。

注意点

• ソーシャルカード（OG プレビュー）はオプトインで、デフォルトでは無効です。 有効にするには init-docs-site.sh に --social を渡してください。通常のスキャフォールドにはソーシャルプラグインも [imaging] 依存関係も Cairo/Pango の CI ステップも含まれないため、システム依存関係なしでビルドでき（通常の mkdocs build では 1 秒もかからずにレンダリングされます）、ユーザーがリッチなリンクプレビューを望み、以下のコストを許容する場合に有効にしてください。すでにスキャフォールド済みのサイトで有効にするには、mkdocs.yml に social プラグインのブロックを、ドキュメントの依存関係に mkdocs-material[imaging] を、docs.yml に Cairo/Pango とキャッシュのステップを追加し、.gitignore に /.cache/ を追加してください（--social が挿入するものと同じスニペットを assets/social/* からコピーします）。
• social プラグインにはシステムの Cairo/Pango と [imaging] 追加機能が必要です。 mkdocs-material[imaging] は cairosvg/pillow を取り込みますが、これらはシステムの libcairo/libpango に依存するため、これらがないとビルドは libcairo の読み込みエラーで中断します。--social を指定すると、docs-workflow.yml.template がそれら（libcairo2-dev libpango1.0-dev libfreetype6-dev …）を apt でインストールし、.cache/plugin/social をキャッシュします。ローカル環境では、macOS なら brew install cairo pango、Linux なら同じ apt パッケージをインストールしてください。--social は .gitignore に /.cache/ も追加します。プラグインはそこにページごとに約 1 枚のカード PNG（数十 MB）とダウンロードしたフォントを書き込みます。キャッシュがない状態でのビルドでは、ページごとにカードを 1 枚レンダリングします（Google Fonts からフォントをネットワーク経由で取得）。キャッシュがあれば数秒で済みます。
• カードのフォントが文字をカバーしていないと、CJK 文字や矢印を含むページタイトルはソーシャルカード上で豆腐（□□□）として表示されます。 プラグインのデフォルトフォント（Roboto）と通常の「Noto Sans」はラテン文字しかサポートしていないため、中国語・日本語・韓国語のタイトルはもちろん、英語のタイトルに含まれる → さえも豆腐として表示されます。add-language.sh は CJK 言語を追加すると、CJK 対応の social.cards_layout_options.font_family（Noto Sans TC/SC/JP/KR）を自動設定しますが、ソーシャルプラグインが存在し、フォントがまだ設定されていない場合に限ります（そのため、zh-TW を追加する前に --social を指定してスキャフォールドするか、その後に自分でフォントを設定してください）。ビルドの結果を信頼するだけでなく、レンダリングされた site/assets/images/social/**/<page>.png を開いて確認してください。
• これらのスクリプトで使う yq は mikefarah yq（v4）で、if/then/else/end 構文には対応していません。これは jq の構文です。(.plugins[] | select(has("x")) | .x.y) = z または += […] を使い、.plugins |= map(if has("x") then … else . end) は使わないでください（lexer: invalid input text "if …" エラーで失敗します）。以前、i18n の第 2 言語追加処理でこの問題が発生しました。新しい式も select() 形式にしてください。
• MkDocs の strict モードでは、docs/ の外を指す相対 .md リンクは拒否されます。 docs/ 内のファイルへの相対リンクは問題ありません。docs/ の外にある .md ファイル（例：リポジトリの TODO.md）へのリンクには、GitHub の絶対 URL を使ってください。docs/ の外にあるディレクトリや .md 以外のファイル（backlog/、pyproject.toml）への相対リンクは INFO に格下げされ、許容されます。テンプレートはすでに正しく設定されています。絶対 URL を「修正」しないでください。
• pymdownx.snippets のインクルードフラグメントは、再帰的な exclude_docs に含める必要があります。 not_in_nav は警告を抑制するだけで、単独の HTML としての公開は防ぎません。テンプレートではルートおよびネストされた _snippets/ ディレクトリを除外しています。
• gh api -X POST .../pages は build_type=workflow の場合は冪等ですが、リポジトリがまだ GitHub にプッシュされていないと 404 Not Found エラーになります。 enable-pages.sh を実行する前に、gh repo view が成功することを確認してください。
• Pages のデプロイワークフローには、ワークフローレベルで permissions: pages: write, id-token: write が必要です。 テンプレートには設定済みです。既存のワークフローに一部をコピーする場合、これを失わないでください。
• copy-to-llm プラグインの repo_url は GitHub URL ではなく SITE URL です。 名前からは分かりにくいので注意してください。
• 既存のユーザードキュメントを自動移行しないでください。 必ずユーザーに確認してください。手作業で整備された docs/ を新しい構造に移行するのは、ユーザーの明示的な判断に委ねるべき、信頼度の高い操作であり、エージェントがデフォルトで行うものではありません。
• .skills/preferences.yaml はリポジトリごとの設定であり、グローバル設定ではありません。 ~/.skills/ や ~/.config/ には書き込まないでください。リポジトリごとに独自の設定があります。
• mkdocs-static-i18n では、theme.language にデフォルト言語コードを設定する必要があります。 設定されていないと、プラグインが警告を出します。add-language.sh は初回実行時に設定します。手作業で一部をコピーする場合は、忘れずに設定してください。
• docs_structure: suffix のみをサポートします。 add-language.sh はサフィックス形式（index.md と index.zh-TW.md を並べる形式）を書き込みます。i18n_structure: folder 設定キーは予約されていますが、まだ実装されていません。folder の設定を mkdocs.yml に貼り付けても、スクリプトがその設定を維持するとは限りません。
• 多言語ビルドを一度だけ実行すると、mkdocs-llmstxt の出力が気付かないうちに破損します。 mkdocs-static-i18n は言語ごとに全体をビルドしますが、llmstxt はページの状態を消去し、各パスで同じルートの llms.txt / llms-full.txt を上書きします。そのため、最後に処理された言語の出力がほぼ空になったり、別の言語の内容になったりする可能性があります。--strict を削除しても警告が隠れるだけで、ファイルは修復されません。デプロイ可能な成果物の作成には、必ず scripts/build-docs-site.py を使ってください。ルートの /llms.txt、/llms-full.txt、.md サイドカーには、意図的にデフォルト言語のみが含まれます。
• add-language.sh は theme.features から navigation.instant を削除します。言語切り替え機能のコンテキストリンクが、インスタントナビゲーションと互換性がないためです。Material のプラグイン自体が警告を出すため、スクリプトはその警告に対応しているだけです。
• 英語の原文がない zh-TW ページでは、技術用語を翻訳しないでください。 用語に関するルール（初出時に括弧内に英語を残し、独自の訳語を作らない）は必須です。スタブテンプレートには、執筆を始める前に著者が確認できるよう、このルールが admonition として挿入されます。

既存サイトの更新（ブートストラップではない場合）

mkdocs.yml がすでに存在する場合は、黙って「アップグレード」しないでください。カスタマイズがテンプレートに合わないことがあります。i18n／llmstxt の修復を明示的に依頼された場合は、まず migrate-i18n-llmstxt.sh で監査してください。変更予定を提示してからのみ適用し、手動対応と報告された形状はすべて維持してください。