configure-site

GitBook サイトを設定する

GitBook ドキュメントサイト全体の作成と保守を行うためのスキルです。write-docs が単一ページの内容を扱うのに対し、このスキルではページ周辺のすべて、つまり構成の設計、リポジトリのひな形作成、GitBook API、ブランディングを扱います。2 つのスキルを併用してください。このスキルは、ページの内容を生成または編集する必要があるときに、write-docs を呼び出します。

GitBook の操作方法

GitBook を操作する方法は 1 つではありません。GitBook の MCP サーバーと REST API があります。現在のセッションで実際に利用できるものを確認し、まず MCP を優先してください。GitBook MCP ツールがすでに接続されている場合は、サイトの作成や設定、変更リクエストの開始、コンテンツの下書きや編集、ドキュメント構成の変更など、対応している操作には直接 API を呼び出すのではなく、MCP ツールを使ってください。これを確認するための検出スクリプトは実行しないでください。利用可能なツールや MCP 接続は把握できているので、その認識に基づいてください。

「まず MCP を優先」とは、通信手段についてのことであり、コンテンツに Git Sync を使わないという意味ではありません。 MCP には変更リクエストのコンテンツプッシュツール（updateChangeRequestContent）があり、接続されているといつでも使いたくなります。しかし、Git Sync がすでに設定されているスペースでは、小規模で対象を絞った編集を超える作業について、ローカルリポジトリのファイルを編集し、Git Sync で GitBook に反映させる方法を引き続き優先してください。スペースが Git Sync と連携していない場合、環境内にローカルチェックアウトがない場合、または変更が小さく、CR を開くのが妥当な場合は、代わりに変更リクエストのプッシュ（MCP または REST）を使ってください。詳しいルールは、write-docs の「Git Sync と変更リクエストによるコンテンツプッシュの選択」を参照してください。ここでも同じルールが適用されます。

このスキルの手順は、特定の通信手段に結び付けず、「組織の一覧を取得する」「サイトを作成する」「セクションを追加する」といった成果を示しています。そのため、どちらの方法を使う場合にも適用できます。GitBook MCP ツールが接続されている場合は、それらを直接呼び出してください。各ツールのスキーマにパラメーターが記載されています。REST API を使う場合は、各手順の正確なエンドポイント、リクエストボディ、想定されるレスポンスが references/api-cheatsheet.md に記載されています。

• GitBook MCP — 以下で説明する機能と同じ機能を読み書きできる、包括的なインターフェースです。より限定的なビューではありません。まだ接続されておらず、タスクの規模がセットアップのメリットに見合う場合（サイト全体の構築や継続的な再構成など。単発の小さな変更は除く）は、セットアップを提案してください。claude mcp add --transport http gitbook-mcp https://mcp.gitbook.com/mcp を実行し、その後 /mcp を実行して OAuth サインインを完了します。または、--header "Authorization: Bearer $GITBOOK_TOKEN" を追加すれば、ブラウザーでの認証手順を省略できます。Codex では、codex mcp add gitbook-mcp --url https://mcp.gitbook.com/mcp を使います。注：これは、公開済みのコンテンツのみを提供する、GitBook の別の読み取り専用「公開ドキュメント」MCP サーバーとは異なります。
• REST API（https://api.gitbook.com/v1） — MCP が接続されていない場合、または MCP が対応していない操作で使う代替手段です。各リクエストのベアラーヘッダーに GITBOOK_TOKEN が必要です。

同じ個人用アクセストークン（https://app.gitbook.com/account/developer から取得）を、どちらの方法でもベアラートークンとして使用できます。MCP では、トークンを貼り付ける方法に代わる、より手軽な手段として OAuth もサポートされています。

トークンが必要になった場合（REST API を使う場合、または OAuth を使わずに MCP を使う場合）は、セッションの開始時にトークンがあるか確認してください。

[ -n "$GITBOOK_TOKEN" ] && echo "Token found" || echo "GITBOOK_TOKEN is not set"

GITBOOK_TOKEN が設定されていない場合は、ユーザーに直接尋ねてください。

1. GitBook の個人用アクセストークンが必要であることを伝えてください。作成するには https://app.gitbook.com/account/developer にアクセスするよう案内してください。
2. トークンを会話に貼り付けるよう依頼してください。受け取ったら、直ちに環境変数としてエクスポートしてください（export GITBOOK_TOKEN=<pasted value>）。回答でトークンを繰り返さないでください。
3. 環境にトークンがあることを確認するまで、API 呼び出しを行わないでください。

トークンをファイルに書き込んだり、回答で表示したり、コミットしたりしないでください。

基本的な制約

何かを始める前に、最も重要な点を理解しておいてください。GitBook では、転送方式にかかわらず、Git Sync のセットアップ以外はほぼすべて行えます。 GitHub／GitLab の認証、リポジトリの選択、ブランチの選択、初回同期の方向の選択は、すべて UI でのみ行えます。REST API も、それをラップする MCP も、Git Sync の結果の状態を読み取ることしかできず、セットアップはできません。サイトまたはスペースを対象とする installGitSyncProviderOnTarget という API 操作はありますが、アカウント接続（OAuth）の手順は引き続きアプリ内で行う必要があり、現時点では GitBook の MCP サーバー経由で利用できません。この操作を使ったワークフローを構築するのではなく、まだ利用できないものとして扱ってください。

現在、Git Sync はサイトレベルで設定するため、まずはこちらを選んでください。 1 つの接続（1 つのリポジトリ、1 つのブランチ）でサイト全体をカバーします。gitbook-docs.yaml で各スペースを独自のディレクトリに割り当てます。これは、このスキルがモノレポに生成する構成と同じ形式です。スペースごとの Git Sync も引き続き利用できますが、現在は例外的な選択肢です。特定のスペースに独立したリポジトリやブランチが必要な場合（たとえば、公開ドキュメントのリポジトリには含められないプライベートスペース）に限って選択してください。

そのため、最もシンプルなエンドツーエンドのワークフローは常に次のとおりです。

1. Claude がローカルにモノレポとして Git リポジトリを生成します（スペースごとに 1 つのディレクトリ）。できれば、各スペースを対応するディレクトリに割り当てた gitbook-docs.yaml をあらかじめ作成し、ツールが使える場合はリモートにプッシュします
2. Claude がサイト、セクション、作成可能な空のスペースを作成します
3. **ユーザーが GitBook で、短く手順を明確に示された UI 操作を 1 回行います。サイトをリポジトリ／ブランチに接続し、スペースとディレクトリの対応関係を確認します。**スペースごとに行う必要はありません
4. Claude がブランディングやカスタマイズを適用します

手順 3 でユーザーの操作が必要なのは避けられませんが、決して不意打ちにならないようにしてください。ユーザー向けに、明確でそのままコピー＆ペーストできる手順を用意してください。参考：references/git-sync-handoff.md。

ユーザーが Git Sync を明示的に希望しない場合は、コンテンツインポートの方法（コンテンツのインポートとテンプレートの適用）に切り替えてください。詳しくは以下と references/api-cheatsheet.md で簡単に説明します。

事前に確認しておくべき情報

これらがわかるまでは、生成を始めないでください。不明な点がある場合は、推測せず、要点を絞った質問を一度だけしてください。（認証は別途扱います。上記の「GitBook との接続方法」を参照してください。）

• 組織 — ユーザーの組織一覧を取得し、一覧をユーザーに見せてから、名前で対象の組織を確認します。組織が1つしかない場合でも確認してください。最初に一度確認しておけば、誤った場所にサイトを作成するリスクを低コストで防げます。選択された organizationId はセッション中保持し、その後の手順を説明する際は UUID ではなく組織名で呼びます。
• サイトのプランと公開範囲 — ユーザーが明示的に別の希望を伝えない限り、type: "ultimate"（Ultimate プラン）と公開設定をデフォルトにします。実際の顧客の多くは、Ultimate の機能（カスタムドメイン、AI アシスタント、高度なカスタマイズ、GitBook の商標を非表示にする機能、カスタムフォント、カスタムロゴ）を必要としています。無料プラン（type: basic）が適しているのは、個人のオープンソースのサイドプロジェクトのような、明らかに重要度が低い用途に限られます。判断に迷う場合は、次のように確認してください。「特にご希望がなければ Ultimate プランで設定します。無料プランのほうがよろしいですか？」 — basic では Ultimate の機能（AI アシスタント、カスタムフォント、カスタムドメインが利用できない）が何も伝えずに使えなくなるほうが、プランを簡単に確認するよりもユーザーを驚かせてしまいます。
• コンテンツの種 — サイトの構築元を確認します。よくある例：
  • 既存の Markdown ファイルが入ったフォルダー — 最もスムーズに始められます
  • いくつかのメモと、参考にしたい競合サイト
  • ドキュメントにしたい内容の説明だけ
  • 再構成したい既存サイト（この場合は、まず現在のサイト構造を取得します）
  • 別のドキュメントプラットフォーム（Mintlify、Docusaurus、ReadTheDocs、GitBook v1）からの移行 — 手順については references/migration-from-other-platforms.md を参照してください。移行には独自の専門知識が必要です。単なるファイルコピーのように扱わないでください。
• API リファレンス用の OpenAPI 仕様 — サイトに API リファレンスのコンテンツが含まれる場合は、OpenAPI 仕様があるか（またはコードベースから生成できるか）を事前に確認します。ある場合、API リファレンスのスペースには、各リソースに対する1段落の概要 README と、1つの builtin:openapi SUMMARY エントリーを用意するだけで済みます。エンドポイントのページを手作業で作るより大幅に手間が少なく、内容が古くなることもありません。手順については references/block-ecosystem.md と references/api-cheatsheet.md を参照してください。エンドポイントのページを手作業で作ることをデフォルトにしないでください — ほとんどの場合、適切な選択ではありません。
• ブランディング — 最低限、プライマリカラー（hex）を確認します。任意で、ロゴの URL（ライトモード用とダークモード用）、ファビコン、フォントの選択（または GitBook のデフォルトから選択）、ヘッダーリンク、フッターのテキストやリンク、テーマプリセット（clean、muted、bold、gradient）も確認します。Ultimate サイトでは、AI アシスタント用のスタータープロンプト（訪問者が尋ねそうな3〜5個の短い質問）も検討します。
• サイト構造 — サイトスペースではなくセクションを使います。サイトに複数のスペースがある場合は、ユーザーとともにセクションの一覧を明確に計画します。各セクションには、タイトル、Font Awesome のアイコン名、説明を設定します。セクションのアイコンと説明はナビゲーションの重要な要素で、訪問者の目にも触れます。事前に確認しておけば、後からセクションごとに更新する手間を省けます。例：[{title: "Guides", icon: "book-open", description: "Concepts and tutorials"}, {title: "API Reference", icon: "code", description: "REST API and SDKs"}, {title: "Changelog", icon: "clock-rotate-left", description: "Updates and release notes"}]。
• Git リモートの希望 — GitHub、GitLab、ローカルのみのいずれかを確認します。質問する前に gh または glab がインストールされているか確認してください。どちらのツールも利用できない場合は、そのことを明確に伝え、次の2つの選択肢を提示します。（1）ローカルでコミットし、「リモートを作成してプッシュする」手順をユーザーへの引き継ぎの冒頭に記載する、または（2）ツールのインストールをユーザーに依頼する。説明なしにローカルのみをデフォルトにしないでください。リモートも手順の案内もないリポジトリになってしまいます。
• サイトの構成 — 単一スペースか複数スペースかを確認します。複数スペースのサイトでは、ナビゲーション上でスペースをまとめるためにセクションを使います。ユーザードキュメント、API リファレンス、変更履歴のように、コンテンツの対象読者が明確に異なる場合に適しています。翻訳版を作成する場合に限り、サイトスペースを直接使用してください。詳しくは references/api-cheatsheet.md を参照してください。

構築前にコンテンツのソースを確認する

ユーザーがコンテンツの種となるもの（リポジトリ、フォルダー、ドキュメントサイトの URL）を指定したら、構成を設計したり、何かをひな形から作成したりする前に、実際に読み取れることを確認してください。

1. ソースを特定して示します。 これから読み取るもの（リポジトリの URL とブランチ、フォルダーのパス、またはサイトの URL）を正確に伝え、確認用にトップレベルの内容（ファイルやページの短い一覧）をユーザーに示します。
2. アクセスできない場合は、そこで止めて伝えます。 Git ホストは、非公開リポジトリに対して 404 を返すことがあります。これは「リポジトリが存在しない」場合と区別できません。ユーザーが指定したリポジトリで 404 またはクローンの失敗が発生した場合は、非公開の可能性があるものとして扱います。失敗した内容を伝え、コンテンツをアクセス可能にする方法（ローカルクローン、アーカイブ、認証済みの gh／glab、公開ミラー）を用意するか、URL を訂正するようユーザーに依頼してください。リポジトリにアクセスできないと判断する前に、認証済みの gh／glab CLI が利用可能か確認してください。
3. ソースを代用してはいけません。 名前が似ているリポジトリやサイト（同一に見えるものも含む）を検索したり、推測したり、代わりに使ったりしないでください。誤ったソースからドキュメントサイトを構築することは、作業を中断して確認を求めるよりもはるかに重大です。ソースを変更する場合は、必ずユーザーの明示的な承認を得てください。

状態を変更する操作の確認ゲート

サイトの作成、スペースの作成、セクションの追加、サイトとスペースの紐付け、カスタマイズの変更は、すべて組織内の全員に即座に表示されるオブジェクトを作成または変更し、後片付けにも相応の手間がかかります。重大な操作として扱ってください。

ルール：これから実行する内容を正確に示した1画面分のプレビューをユーザーに提示し、明示的な「はい」を得るまでは、状態を変更してはいけません。

適切なプレビューは、簡潔で具体的です。

組織 Acme Inc（org_abc123）で、次の操作を実行します。

• サイト **「Acme Platform Docs」**を作成（タイプ：ultimate、公開範囲：公開）
• 空のスペースを3つ作成：Guides、API Reference、Changelog
• Guides をデフォルトセクションとして追加し、API Reference と Changelog のセクションを作成

続行しますか？（はい／いいえ）

不適切なプレビューは、曖昧なもの（「これからサイトを作成します」）や、長い説明に埋もれたものです。ひと目で内容がわかるようにしてください。

同じルールは、サイト、スペース、セクション、カスタマイズの上書き設定を削除するなどの破壊的な操作にも適用されます。ただし、曖昧さがないよう、より明確に伝えてください（「サイト Acme Platform Docs と、そのサイトに含まれる3つのスペースを削除します。スペースとサイトは7日間復元できますが、その後は完全に削除されます。よろしいですか？」）。

構成の設計段階でユーザーが複数ステップの計画をすでに承認している場合、その計画内の個々の操作について、毎回あらためて確認する必要はありません。ただし、計画に変更がある場合（スペースの追加、公開範囲の変更など）は、再度確認を取ってください。

読み取り専用の操作（取得や一覧表示）では、確認は不要です。

変更リクエストのプッシュ後：2 つのリンクが必須です

このスキル（またはページ作成を委任する write-docs）が、MCP の updateChangeRequestContent／create_change_request／submit_or_merge_change_request の厳選ツール、invoke_operation、または REST の同等機能を使って変更リクエスト経由でコンテンツをプッシュした場合は、次の両方を毎回ユーザーに報告するまで、編集は完了していません。

1. 変更リクエストの差分／エディターリンク（urls.app） — GitBook アプリで変更を確認するためのリンクです。
2. サイトのプレビューリンク — 変更が反映されたドキュメントのレンダリング結果です。これは別途確認する必要があります。サイトの URL は変更リクエストオブジェクトではなく Site オブジェクトにあり（サイトが公開されている場合は urls.published、それ以外の場合は urls.preview）、末尾のスラッシュを取り除いてから /~/changes/<number>/ を追加する必要があります。このセグメントがないと、リンクにはこの変更リクエストではなく、サイトの現在のコンテンツが表示されます。正常に読み込まれますが、表示される内容が違います。

これは上記の確認ゲートと同等の厳守ルールであり、時間に余裕があるときに追加するだけの気配りではありません。具体的な解決手順については、write-docs の「変更リクエストが関係する場合は、常に 2 つのリンクが必須です」と、cr-create スキルの「プレビューリンクの提示」を参照してください（MCP：getSpaceById → list_sites／get_site_structure、または各サイトの site-spaces からサイトを特定 → .urls.preview のために getSiteById。REST：同等の連続した GET 呼び出し）。スペースが公開済みサイトに紐付いていない場合は、差分リンクだけを説明なしで提示するのではなく、その旨を明確に伝えてください。

サイト構造の設計

GitBook でファイルを作成したり、何かを作成したりする前に、構造を決めてユーザーに確認してください。ドキュメントサイトの公開がうまくいかない最大の原因は、構造が不十分なことです。

このステップの成果物は、理想的には次の 3 つからなる簡潔な計画です。

1. スペースの一覧 — 内容に一貫性のあるまとまりごとに 1 つのスペースを作成します。スペースの数は少なく保ちます（通常は 1～4 個です）。スペースはナビゲーションと Git Sync の単位なので、同じ読者層向けのコンテンツを複数のスペースに分散させないでください。
2. セクションのグループ分け（複数のスペースがある場合）— セクションはサイトのナビゲーションにおける最上位の区分です。例：「製品」／「開発者」／「リソース」。セクションには 1 つ以上のスペースを配置できます。
3. スペースごとのページツリー — フォルダーとページ、および各ページの概要（1～2 文）を記載します。階層の深さはコンテンツに合わせます。通常は浅いツリー（1～2 階層）が最適です。

生の入力から構造計画を作成するためのヒューリスティック一式は、references/site-structure-design.md にあります。重要度の高いサイトで初めてこの作業を行う際は、必ず読んでください。**ファイルのひな形を作成する前に、必ず計画をユーザーに示し、明示的な承認を得てください。**Git 内での再構成は簡単ですが、サイトを公開してインデックス化した後ではコストがかかります。

ユーザーが 1 つにまとめた指示を出した場合の確認について、注意点があります。*「構造を計画してから、ひな形を作成してください」*のような指示は、確認を省略したくなるかもしれません。しかし、省略しないでください。計画を見やすく明確な形式で提示し、「はい」という返答を待ちます。または、指示が非常に明確だったために、すでにひな形の作成を始めている場合は、計画で決めた内容を提示したうえで、簡単に方向修正できる機会を一度設けます（「この内容に誤りがあれば、先に進む前にやり直しますのでお知らせください」）。重要なのは、生成された 20 個のファイルを目の前にする前にユーザーが計画を確認でき、やり直しもまだ容易な段階であることです。

リポジトリのスキャフォールディング

構成が決まったら、単一スペースのサイトでもリポジトリをモノレポとして構成します。これが一貫性と将来性を保つ方法です。各スペースはディレクトリで、その中に独自の README.md（ホームページ）と SUMMARY.md（目次）を配置します。任意で、スペースごとの変数や再利用可能なコンテンツブロックを格納する .gitbook/ フォルダーや、高度な同期設定を行う .gitbook.yaml も追加できます。

3 つのスペースがあるサイトの構成例：

my-docs/
├── .gitignore
├── README.md                    # repo-level readme (not a space homepage)
├── guides/                      # space 1
│   ├── README.md                # space homepage
│   ├── SUMMARY.md
│   ├── .gitbook/
│   │   └── vars.yaml            # optional: space-level variables
│   ├── getting-started/
│   │   ├── installation.md
│   │   └── quickstart.md
│   └── concepts/
│       └── ...
├── api-reference/               # space 2
│   ├── README.md
│   ├── SUMMARY.md
│   └── endpoints/
│       └── ...
└── changelog/                   # space 3
    ├── README.md
    └── SUMMARY.md

この構成でつまずきやすい点をいくつか紹介します。

• .gitbook.yaml は任意です。 GitBook は、各スペースに README.md と SUMMARY.md を置くデフォルトの規約で問題なく動作します。ルートを上書きしたり、リダイレクトを定義したり、その他デフォルト以外の設定が必要な場合にのみ .gitbook.yaml を追加してください。付属のサンプルサイト（references/example-site/）には .gitbook.yaml ファイルが一つもありませんが、問題なく動作します。
• .gitbook/vars.yaml には、式構文を使ってページから参照できるスペース単位の変数を格納します（例：support_email: [email protected] を <code class="expression">space.vars.support_email</code> として参照します）。多くのページに登場する値に便利です。write-docs / references/frontmatter.md を参照してください。{% vars.… %} は 使用しないでください。
• .gitbook/includes/<name>.md には再利用可能なコンテンツブロックを格納します。これは、{% include "...persona-switcher" %} を使って複数のページに埋め込めるスニペットです。定型文をコピーして貼り付ける代わりに、これらを使用してください。
• スペースのディレクトリ名（例：guides/）は、サイト全体の Git Sync を設定する際に、ユーザーが Content mapping でそのスペースに割り当てる名前です。サイトの「Project directory」フィールドとは異なります。このフィールドは gitbook-docs.yaml 自体がある場所（この構成ではリポジトリのルート）のみを指定します。この 2 つを混同しないでください。references/git-sync-handoff.md を参照してください。
• リポジトリのルートに、すべてのスペースとそのディレクトリを対応付ける gitbook-docs.yaml をあらかじめ作成しておくことを検討してください（形式については references/git-sync-handoff.md を参照してください）。GitBook は初回の同期時にこれを読み込むため、セットアップ時にユーザーが手作業で入力する項目を減らせます。

必要な場合の最小限の .gitbook.yaml は次のとおりです。

root: ./
structure:
  readme: README.md
  summary: SUMMARY.md

リポジトリレベルの README と .gitignore

リポジトリレベルの README.md（リポジトリのトップに置き、スペース内には置かない）では、フォルダーの内容と公開済みサイトとの関係を説明します。ドキュメントそのものを重複させないでください。短い段落で十分です。

# my-docs

Source for the [My Product docs site](https://docs.example.com). Each top-level folder
is a separate GitBook space; edits flow in both directions via Git Sync once configured.

.gitignore には、OS の不要ファイルやエディター設定がリポジトリに含まれないように記述します。一般的なデフォルト設定は次のとおりです。

.DS_Store
Thumbs.db
*.swp
*.swo
.idea/
.vscode/

チームにほかの生成物（例：別の場所にあるソースから生成した OpenAPI 仕様書）がある場合は、それらも追加してください。

SUMMARY.md の生成 — フォルダーから推測せず、ナビゲーションを確認する

最もよくある足場作成の誤りは、ファイルツリーをたどって SUMMARY.md を生成することです。README を先頭に置き、ほかのすべてのファイルを README の下にインデントした子項目として並べます。こうすると、ナビゲーションは見づらくなります。すべてのページが「ホームページの子」になり、フォルダー名が読者にとって意味があるかどうかに関係なくグループ名となり、情報アーキテクチャがユーザーのメンタルモデルではなくファイルシステムを反映してしまいます。

正しい進め方は、次の順序です。

1. 構成を設計する際に、ユーザーから希望するナビゲーションを確認します。 トップレベルのページと、各スペースに含めるグループ名を明示的に挙げてもらいます。ここでフォルダー名を実際のナビゲーションに合わせます。また、ユーザーから「やはり Authentication は Concepts の下ではなく、トップレベルのページにしたい」と伝えてもらうこともできます。

2. 合意したナビゲーションに合わせてフォルダーを構成します。逆にしてはいけません。 あるスペースに「Getting started」「Concepts」「Tutorials」の 3 つのグループを設ける場合、そのスペースのディレクトリにも、それぞれの名前をスラッグ化した 3 つのサブフォルダーを作り、各フォルダーにページを配置します。たまたま存在するサブフォルダーから 4 つ目のグループを自動的に抽出しないでください。

3. ユーザーと合意した明示的な構成で SUMMARY.md を記述します。 GitBook が認識する構文は次のとおりです。

   # Table of contents
   
   * [Space homepage](README.md)
   * [Top-level page A](top-level-a.md)
   * [Top-level page B](top-level-b.md)
   
   ## First group
   
   * [Page in group](first-group/page.md)
   * [Another page](first-group/another.md)
   
   ## Second group
   
   * [Page](second-group/page.md)
   

   主な構成ルール：

   • README.md は最上部に単独の行として置き、親ではなく兄弟項目にします。 ほかのトップレベルページも兄弟項目として続けます。
   • ## グループ名 の見出しでグループを導入します。 グループ内のページは、README の下にインデントするのではなく、見出しの直下にフラットな箇条書きとして並べます。
   • 機械的に「 README.md」の下へすべてを入れ子にする方法は避けてください。* ナビゲーション全体がホームページの下にある 1 つのツリーにまとまり、サイドバーではすべてのページがホームページの子ページに見えてしまいます。
   • グループ名はフォルダー名ではなく、ユーザーから確認します。 フォルダーのスラッグには「concepts/」を使いつつ、グループ見出しには、より分かりやすい「How it works」を使うこともできます。
   • ページごとに箇条書き項目を 1 つだけ記述し、余計な書式は使いません。 SUMMARY には太字や説明を含めません。説明はページのフロントマターに記述します。

4. 通常の箇条書きとは異なる特別なパターン：

   • OpenAPI から自動生成されるエンドポイントページでは、箇条書きの内容にフェンス付き YAML ブロックを使います（type: builtin:openapi — references/api-cheatsheet.md を参照）。
   • 外部リンクには * [タイトル](https://...) を使うと、ナビゲーションに外部リンクとして表示されます。
   • SUMMARY.md のスペース間リンクには、本文と同じ https://app.gitbook.com/s/<spaceId>/<path> 形式を使います。パスに .md のサフィックスは付けません。足場作成時にはセンチネル形式（XSPACE_<KEY>）を記述し、スペース作成後に解決します。references/cross-space-links.md を参照してください。

足場作成用のヘルパーがフォルダーをたどって SUMMARY.md を自動生成する場合、冪等にし、既存のファイルはスキップするようにしてください。ユーザーが編集した SUMMARY.md を、何も知らせずに上書きしてはいけません。そうすると、手作業で調整したナビゲーションが失われてしまいます。

ページごとの Markdown — write-docs を基準にしつつ、リッチブロックを活用してください

すべての Markdown ファイル — README.md、SUMMARY.md、各ページ — では、write-docs スキルに従ってください。これは、次の項目についての正式なリファレンスです。

• フロントマター（icon: フィールドを含む）。アイコンは fa- の接頭辞を付けずに Font Awesome の名前を指定します（例：book-open、bolt、house、code、puzzle-piece、id-card、circle-dollar-to-slot）。名前を適当に作らず、Font Awesome のカタログから選んでください。サンプルサイトでは、ほぼすべてのページのフロントマターでこれらを使用しています。
• レイアウトフラグ。layout: width: wide（選択的に使用します。マーケティングスタイルのランディングページ、Updates タイムラインを含む変更履歴ページ、複数列のブロックや実際に幅の広い表があるページなどに使用してください。すべてのスペースのホームページで、デフォルトで wide にしないでください。カードテーブルのあるドキュメントのランディングページを含め、ドキュメントには GitBook のデフォルト幅が適しています。wide はヒーロースタイルのマーケティングレイアウト向けであり、通常のドキュメント向けではありません）、cover: 画像、ページごとの表示フラグ（title.visible、tableOfContents.visible など）。
• SUMMARY.md の文法。厳格な形式です。ページごとに箇条書きを1つ、任意で ## Group name 見出しを使用し、余分な書式は追加しません。また、仕様からエンドポイントページを自動生成するための特別な type: builtin:openapi 構文もあります。
• リッチブロック — タブ、ヒント、ステッパー、列、カードテーブル、折りたたみ、埋め込み、{% if visitor.claims... %} による条件付きコンテンツ、OpenAPI ブロック、Updates ブロック（変更履歴）、再利用可能なコンテンツのインクルード。
• CommonMark との GitBook 独自の Markdown の違い。

ここでこれらを独自に考案しないでください。バンドルされている references/example-site/ が、慣用的なコンテンツの実践的なリファレンスとして最適です。

適切なブロックを選ぶ — デフォルト任せにせず、積極的に

よくある失敗パターンは、Claude が「動く」ドキュメントを生成しても、すべてにプレーンな Markdown を使い、GitBook サイトを本格的なプロダクトらしく見せるリッチブロックを活用できていないことです。スキルでは、プレーンな文章や箇条書きに頼るのではなく、専用ブロックを積極的に選んでください。 身につけておくべき具体的なパターンは次のとおりです。

• 変更履歴 → {% updates %} ブロックに {% update date="..." tags="..." %} エントリを使用します。RSS を自動生成し、タグ（.gitbook/tags.yaml で定義）にも対応しています。## YYYY-MM-DD の見出しは使わないでください。適切な形式ではありません。
• API エンドポイントのリファレンス → OpenAPI 仕様を一度アップロードし、SUMMARY.md の type: builtin:openapi でページを自動生成します。エンドポイントのページを手作業で作成しないでください。内容が乖離してしまいますし、いずれにしても仕様が正式な情報源です。ユーザーが仕様を用意していない場合は、文章だけで作成するのではなく、最小限の仕様書を作成することを提案してください。
• ステートマシン、フロー、シーケンス、シンプルなアーキテクチャ → ```mermaid のコードフェンスを使用します。ASCII でボックスや矢印を描かないでください。Mermaid はサポートされており、きれいに表示され、スクリーンリーダーにも対応しています。
• スペースのホームページ → 通常のドキュメントのランディングページには、GitBook のデフォルトレイアウトを使います（目次を表示し、幅はデフォルト）。layout: width: wide を使うのは、ページが本当にマーケティング向けのスタイルの場合に限ります。たとえば、ヒーロー画像、通常より大きなカードグリッド、複数列のダッシュボードレイアウトがある場合です。ドキュメントではデフォルトが適切です。
• 「目的に合わせた選択」コンテンツ → カードテーブル（<table data-view="cards">）を使います。HTML は冗長ですが、表示結果はどの Markdown の代替案よりも優れています。
• 左右に並べる導入パターン → {% columns %} ブロックを使用します。50/50 の 2 列が標準です。
• 3 か所以上で繰り返される定型文 → .gitbook/includes/<name>.md と {% include "..." %} を使用します。
• 繰り返し使うリテラル（環境変数の URL、サポート用メールアドレス、バージョンの固定値） → .gitbook/vars.yaml と <code class="expression">space.vars.<name></code> を使用します。
• 複数言語のコードサンプル → {% tabs %} ブロックを使用します。
• 3 ステップ以上の順序付きウォークスルー → {% stepper %} ブロックを使用します。

各ブロックの使用例と、問題の兆候と修正方法をまとめた判断表を含む完全なガイドは、references/block-ecosystem.md にあります。重要度の高いページを生成する前に必ず読み、作成する各コンテンツ領域について判断表に沿って検討してください。 プレーンな Markdown を使う前に、「この内容に適した専用ブロックはあるか？」と確認します。

スペース間リンク

複数のスペースで構成されるサイトでは、スペース間リンクが必要です。リンクがあることで、サイトは個別のマニュアルの寄せ集めではなく、ひとつにつながったプロダクトとして感じられます。リンクを避けるためにコンテンツを重複させたり、リンクを省いたりしないでください。 スペース間リンクは GitBook の主要機能です。ただし、正しく表示するには実際のスペース ID が必要で、ID はサイト作成後にしか取得できません。

Markdown では、リンク先スペースの GitBook URL への通常のリンクを記述します。

For the conceptual side, see the [Authentication concept page](https://app.gitbook.com/s/<spaceId>/concepts/authentication).

GitBook は、カスタムドメインの有無にかかわらず、レンダリング時に https://app.gitbook.com/s/<spaceId>/<path> を解決します。内部的には、スペース ID が設定された ContentRefPage または ContentRefSpace のコンテンツ参照ですが、Markdown では URL として表示されます。

スキャフォールディングの流れ：

1. スキャフォールディング中は、計画したスペースごとに XSPACE_ を先頭に付けた仮のスペース ID を使って、スペース間リンクを記述します。サフィックスには、構成計画で使用したスペースのスラッグを指定します。

   See the [Authentication concept page](https://app.gitbook.com/s/XSPACE_GUIDES/concepts/authentication).
   For the full reference, see the [API Reference](https://app.gitbook.com/s/XSPACE_API/).
   

   これらは存在しない GitBook スペースへの有効な Markdown リンクです。パーサーでエラーにならず、簡単に grep で検索でき、Git を介しても問題なく往復できます。

2. スペース作成後は、新しい各スペースの実際の ID を取得したら、すべての Markdown ファイルを確認し、XSPACE_<KEY> を実際のスペース ID に置き換えます。

   sed -i \
     -e "s|XSPACE_GUIDES|${GUIDES_SPACE_ID}|g" \
     -e "s|XSPACE_API|${API_SPACE_ID}|g" \
     -e "s|XSPACE_CHANGELOG|${CHANGELOG_SPACE_ID}|g" \
     $(find . -name '*.md' -not -path './.git/*')
   

3. 解決結果をコミットしてプッシュします。GitBook は Git Sync 経由で変更を取り込み、次回のレンダリング時にリンクが解決されます。

実装を整理するには、リポジトリのルートに、仮キーとスペース ID の対応を記録した cross-space-links.yaml を作成後に生成して保存します。これにより、誰かがスクリプトを再実行した場合も、同じ結果を再現できます。アンカーリンクやページ固有リンク、解決スクリプトのサンプルを含む全体のパターンについては、references/cross-space-links.md を参照してください。

この内容を書き込む場所： スキャフォールド（仮 ID を使用）、スペースをまたいで生成する Markdown コンテンツ、作成後の解決ステップです。スキャフォールディング中に app.gitbook.com/s/<id>/... の実際のリンクを書こうとしないでください。ID はまだ存在せず、推測した ID はリンク切れになります。

サンプルコンテンツの参照先

references/example-site/ には、このスキルに同梱された、実運用を想定した GitBook サイトの厳選スナップショットが含まれています。元のサイトは 12 個のスペース（ホーム、3 つの製品スペース、開発者向け API の 3 つのバージョン、3 つのガイドスペース、パートナー、変更履歴、および外部コンテンツ用の connections/ ツリー）で構成され、コンテンツファイルは約 200 個あります。同梱されたスナップショットでは、ファイル数の上限に収めるため、約 150 個を残しています。

まず references/example-site/PRUNE-NOTES.md を読んでください。何を残し、何を削除したかが詳しく説明されており、特定のパターンを確認するのに最適なファイルも記載されています。要点は次のとおりです。

• 各スペースの構造的な骨組みはすべて維持されています。README.md、SUMMARY.md、.gitbook/vars.yaml、.gitbook/includes/ が含まれます。
• developers/v2/ は、基準となるサンプルとして全体を維持しています。developers/v1/（レガシー）と developers/v3/（ベータ）は削除しました。どちらも、バージョン固有のコンテンツの違いを除けば、構造は v2 と同一だったためです。複数バージョンの API ドキュメントのパターンは PRUNE-NOTES.md に記載されており、structure.json で確認できます。
• connections/ — 各サブフォルダー（blog/、community/、youtube/）には、メタデータのパターンを学べるよう、index.html と代表的な記事を 1 つ残しています。
• customization.json と structure.json は、削除されたスペースやページも含め、元のサイト全体を記述する完全な API エクスポートです。各スペース内の SUMMARY.md ファイルにも元のツリーが記載されています。そこにあるリンクの一部が削除済みのページを指しているのは想定どおりです。

確認すべき主なファイルを、示したいパターン別にまとめます。

パターン	参照するファイル
更新ブロックとタグ	changelog/README.md + changelog/.gitbook/tags.yaml
builtin:openapi の SUMMARY パターン	developers/v2/SUMMARY.md（コードフェンス内の YAML の箇条書きを確認）
Mermaid 図（フローチャート、シーケンス図）	products/payments/concepts/payment-lifecycle.md、developers/v2/identity-api/README.md
レイアウトの width: wide とカバー画像	home/README.md、developers/v2/README.md
ナビゲーション用カードテーブル	home/README.md、partners/README.md
{% if visitor.claims... %} による条件付きコンテンツ	products/payments/accept-payments/take-a-payment.md
タブとステッパーの併用	developers/v2/getting-started/quickstart.md、developers/v2/getting-started/authentication.md
コードサンプル付きの Webhook ドキュメント	developers/v2/webhooks/verifying-signatures.md
再利用可能なコンテンツインクルード	home/.gitbook/includes/persona-switcher.md
.gitbook/vars.yaml の変数	任意のスペースの .gitbook/vars.yaml
グループ化された SUMMARY.md（## Heading によるセクション）	任意のスペースの SUMMARY.md ファイル

同梱されたスナップショットにないパターン（たとえば、レガシー版とベータ版の API スペースを並べて扱う場合や、外部コンテンツの記事カタログ全体）が必要なときは、構造の正式な情報源である structure.json を参照してください。また、削除されたコンテンツが示していたパターンは PRUNE-NOTES.md に記載されています。

スキャフォールディングの後：

cd my-docs
git init
git add .
git commit -m "Initial scaffold"

ユーザーがリモートリポジトリを希望し、gh または glab が利用可能な場合：

# GitHub
gh repo create <name> --private --source=. --push

# GitLab
glab repo create <name> --private && git push -u origin main

どちらのツールも利用できない場合は、スキャフォールディングが完了する前に、そのことを明示してください。有効な方法は次の 2 つです。

• ローカルのみのリポジトリにして、引き継ぎ時にリモートの設定手順を案内する。 ローカルでコミットし、引き継ぎメモにユーザー向けの「ステップ 0」として、次のように記載します。「お使いのマシンで、<name> という名前のプライベートな GitHub または GitLab リポジトリを作成し、このディレクトリで git remote add origin <url> && git push -u origin main を実行してください。」 これは GitBook UI の手順より前に記載してください。Git Sync で接続するには、その前にリポジトリをプッシュする必要があります。
• gh または glab のインストールをユーザーに依頼する。 今後もサイトを作成する予定があるなら、このツールは役に立ちます。

ローカルのみの構成を黙って既定にしないでください。リモートも追加方法の案内もないリポジトリでは、ユーザーが Git Sync を設定しようとしたときに問題になります。

移行とコンテンツ品質

実際のビルドの多くは新規構築ではなく、別のドキュメントプラットフォーム（Mintlify、Docusaurus、ReadTheDocs、旧GitBook）からの移行や、既存のMarkdownの再構成です。こうした作業には「新しいサイトを作る」とは異なる独自の注意点があります。ここを誤ると、ドキュメントサイトのように見えても、機械が生成したような読み心地のものになってしまいます。

ワークフローの全容は references/migration-from-other-platforms.md にあります。要点は次のとおりです。

作り直す前に、まず元の構成を再現します。 ユーザーが既存の公開ドキュメントサイトを持っている場合、ホームページのコンテンツを生成する前に、表示されているランディングページを取得して確認します。現在の情報アーキテクチャが仕様です。ユーザーがその構成にした理由は、Markdownファイルだけを見ても分からないことが多いためです。元のサイトにすでに機能する答えがあるのに、カードグリッドやヒーローブロック、「新着情報」セクションを一から考案することは、コンテンツ品質に関する失敗の最も一般的なパターンです。

一括エクスポートだけでは、コンテンツを網羅できないことがほとんどです。 Mintlifyの llms-full.txt、ReadTheDocsのHTMLスクレイピング、その他のAI向けエクスポートでは、表示されるコンテンツ（生のマークアップとして出力されたカスタムコンポーネント、インラインに展開されたAIプロンプトブロック、APIテーブルから欠落したパラメーター名など）が削除されることがよくあります。一括変換の後、元のサイトと照らし合わせて表示内容を抜き取り確認し、欠落しているコンテンツがあれば明示します。エクスポートがすべてだと装わないでください。

すべてのページではなく、要となるページに注力します。 280ページを移行するからといって、GitBookの記法を使って280ページを一つずつ手作業で作り直す必要はありません。適切な方法は、その他の大半のページを一括変換したうえで、ホームページ、スペースごとのトップレベルのランディングページ、代表的なハウツーなど、4～6ページの要となるページを、ブロックのエコシステム全体を使って意図的に再構築することです。残りのページは、反復的に標準に合わせていけばよいでしょう。

フォーマット調整は、手順として明確に含めます。 単純なMarkdown変換では、不要なものが残ります（他プラットフォームのコンポーネントタグ、不正なコードフェンス、壊れた内部リンクなど）。一括変換の後、最初のコミットの前にクリーンアップを行い、未対応のコンポーネントを削除し、コードフェンスを統一し、/docs/... のパスをGitBookのURLまたは相対パスに書き換えます。この手順を省くと、リポジトリはほぼ正しく表示される状態にとどまります。

存在しないフロントマターを自動生成しないでください。 元のサイトにアイコンがなかった場合、URLのスラッグからアイコンを自動選択しないでください。場違いな歯車アイコンだらけになります。元のサイトに説明文がなかった場合は、フィールドを空欄にしてください。Source: <url> で代用しないでください。そのテキストがサイドバーのプレビューや検索結果に表示されてしまいます。

APIリファレンスにはOpenAPIを優先します。 移行元のサイトにAPIリファレンスがあり、OpenAPI仕様を入手できる場合（またはコードベースから生成できる場合）は、リファレンスのスペース全体を builtin:openapi に通します。手作業で変換した70ページのリファレンスは、通常、自動生成した3ファイルよりも質が低くなります。

内部リンクの変換はページごとではなく、一括で行います。 構成が決まったら、すべてのMarkdownファイルを調べ、/docs/... のリンクを、スペース内なら相対 .md パスに、スペースをまたぐ場合は https://app.gitbook.com/s/<spaceId>/<path> URLに書き換えます。ページを作りながら個別に変換すると、リンクに一貫性がなくなります。スラッグとパスの対応表を使って一括処理するほうが、はるかに確実です。

コンテンツを再生成するヘルパースクリプトには注意します。 変換ツールやSUMMARY生成ツールを使う場合は、デフォルトで冪等になるようにしてください。既存のファイルはスキップします。2回目の実行で手作業で調整したホームページを上書きしてしまうのは、危険な落とし穴です。手作業で編集したコンテンツが含まれている可能性のあるディレクトリに対して、rm -rf <space>/ を決して実行しないでください。再生成が必要な場合は、<space>/_generated/ に書き出し、マージするか差分を確認してください。

GitBook を操作してサイトを構築する

以下では、エンドポイントの呼び出しではなく、実現する結果を手順として説明します。上記の「GitBook との通信方法」で選んだトランスポートを使用してください。REST API を使用する場合、各手順の正確なエンドポイント、リクエストボディ、想定されるレスポンスはすべて references/api-cheatsheet.md に記載されています。呼び出しを行う前に必ず読んでください。スキーマには注意すべき点があり、特にカスタマイズのスキーマは複雑です。MCP を使用する場合は、同じ手順に対応するツールがあります。REST のパスを調べるのではなく、各ツールのスキーマを確認してください。

新しいサイトの標準的な手順

1. アクセス権を確認し、組織を見つける：認証されたユーザーを確認してから、組織の一覧を取得します。
2. サイトを作成する：{title, type, visibility, spaces?} を指定します。デフォルトは Ultimate（type: "ultimate"）にします。無料の type: "basic" を使用するのは、ユーザーが明示的に希望した場合に限ります。まだスペースがない場合は spaces を含めないでください。スペースは後から追加できます。
3. スペースの作成方法を決める。方法は2つあります。
   • サイト全体の Git Sync（推奨、デフォルト）：ユーザーに、サイトのサイドバーから一度 Git Sync を開き、リポジトリとブランチを接続して、Content mapping で各スペースをそのディレクトリに割り当てるよう案内します。この一度の UI 操作で、すべてのスペースがサイトに作成・リンクされ、すべてのスペースの同期が一括で設定されます。このスキルの役割は、この操作を一度で完了できるよう、具体的でそのまま使える手順を案内することです。references/git-sync-handoff.md を参照してください。
   • プログラム優先：空のスペースを直接作成し、サイトスペースとしてサイトに追加してから、コンテンツのインポートまたはテンプレートの適用でコンテンツを読み込みます。双方向同期を希望する場合、ユーザーは後で UI から Git Sync を設定する必要があります。その際も、スペースごとではなく、デフォルトとしてサイト全体の設定を案内してください。
4. セクションを追加する（ナビゲーションをグループ化した複数スペースのサイトの場合）：セクションは、スペースにタイトルと任意のアイコンを関連付けて作成します。
5. スペース間リンクのセンチネルを解決する：生成された Markdown に XSPACE_<KEY> のプレースホルダーが含まれている場合（スペースをまたぐリンクがあれば含まれているはずです）、手順3または4で返された実際のスペース ID に置き換えます。置換スクリプトについては references/cross-space-links.md を参照してください。変更をコミットしてプッシュします。次回の Git Sync で反映されます。
6. カスタマイズを適用する（ブランディング）：スキーマ全体は幅広く、テーマプリセット、カラー（それぞれ {light, dark} のテーマ別ペア）、ファビコン、ヘッダー（ロゴ、プライマリリンク、リンク）、フッター（リンクのグループ、著作権表示）、テーマ（デフォルトのライト／ダーク、切り替え可能かどうか）、AI モード、PDF エクスポートなどが含まれます。一般的なブランディングの設定例は references/customization-recipes.md にあります。変更する項目だけを変更してください。まず現在の設定を取得し、メモリ上で変更してから、不完全なペイロードを推測して書き込むのではなく、完全な結果を書き戻してください。
7. 確認する：サイトの構造を取得して最終的なツリーを確認し、カスタマイズを取得して設定を確認します。

多言語サイトと自動翻訳スペース

GitBook は自動翻訳サイトスペースに対応しています。Git と同期された英語のスペースを、他の言語への自動翻訳と組み合わせられます。翻訳は Git リポジトリ内に個別のスペースとして存在するのではなく、すべて GitBook 内にあり、各セクションの設定から UI を通じて構成します。同じセクションの下に、language が異なり gitSync フィールドを持たない追加の site-space オブジェクトとして表示されます。

実際には、次のようになります。

• リポジトリ内に言語ごとのディレクトリを作成しないでください。 Git リポジトリには、トピックごとに英語のスペースが 1 つあります。このスキルでは、各コンテンツ領域につき 1 セットの Markdown ファイルだけを作成します。
• 各セクションには複数のサイトスペースを含められます。 「Payments」セクションには、Payments（en、Git 同期済み）、Payments (FR)（fr、自動生成）、Payments (DE)（de、自動生成）などが含まれる場合があります。構造のレスポンスにはすべてが一覧表示されますが、Git Sync の引き継ぎが必要なのは英語のスペースだけです。
• localizedTitle はあらゆる場所に表示されます。 セクション、セクショングループ、ヘッダーリンク、フッターリンク、サイトタイトル自体にはすべて、localizedTitle: {de: "...", fr: "...", ...} というマップが含まれます。カスタマイズ内容を確認するときは、ユーザーが英語だけで設定したフィールドにも翻訳が表示されることを想定してください。依頼がない限り、これらを削除しないでください。
• 自動翻訳は現在、UI でのみ利用できる機能です。ユーザーがセクションでの有効化を希望する場合は、サイト全体の Git Sync の引き継ぎに含めてください。「Git Sync の設定後、Site → Sections → Payments → Translations に移動し、必要な言語を有効にしてください。」

ユーザーが「5 言語のドキュメントサイト」を求めた場合、Git 上に英語のコンテンツツリーを 1 つ用意し、UI でセクションごとに自動翻訳を有効にするのが正しい対応です。Markdown のコピーを 5 つ作るのではありません。

セクショングループ

サイトのナビゲーション構造には、次の 3 つの階層レベルを設定できます。

1. ルートにあるサイトスペース（セクションのないフラットなサイト）
2. サイトスペースを含むセクション（一般的な複数スペースのサイト）
3. セクションを含み、さらにそのセクションがサイトスペースを含むセクショングループ（関連するセクションをまとめるために使用します。例：「Products」グループに Payments／Identity／Connect の各セクションを含める）

サイト構造のレスポンスは再帰的です。セクショングループの sections 配列には、セクションと他のセクショングループの両方を格納できます。構造を設計するときは、トップナビゲーションで視覚的にまとめるメリットがある、密接に関連したセクションが 3 つ以上ある場合に限り、セクショングループを使用してください。2 つのセクションだけのサイトでは、ルートレベルにセクションを配置したほうが明確です。

既存サイトの更新

すでに存在するサイトの変更を依頼された場合は、必ず最初に現在の状態を取得してください。

• サイトのメタデータ
• 構造（セクションとスペース）
• ブランディングのためのカスタマイズ（サイトレベルまたはサイトスペースごと）

その後、全体を置き換えるのではなく、対象を絞って変更してください。1 つのフィールドだけを変更する場合、カスタマイズのペイロード全体を置き換えないでください。現在の設定を取得し、メモリ上で変更してから、変更を反映した全体を書き戻してください。

コンテンツのインポートと Git Sync の使い分け

• コンテンツのインポートは、外部のコンテンツ（ウェブサイトの URL やファイル一式など）をスペースに取り込むための機能です。他のドキュメントツールからの一度限りの移行に適しています。
• Git Syncは、Git リポジトリとサイト（フォールバックとして個々のスペースも可）との継続的な双方向同期のための機能です。標準的なフローでは、これを優先します。
• Git と GitBook のどちらにもない場所（例：Notion のエクスポート）に、すでに適切なコンテンツがある場合は、まずインポートし、その後、必要に応じて Git Sync を有効にしてください。

ブランディングとカスタマイズ

SiteCustomizationSettings スキーマは大規模です。同梱されている references/example-site/customization.json は、本番環境を想定したデモから実際にエクスポートされたもので、最も役立つ参考資料です。カスタマイズ用のペイロードを作成する前に確認してください。ネストされたすべてのフィールドの組み合わせ方、localizedTitle のマッピングの仕組み、条件付きヘッダーリンクの構造が示されています。

すべてのフィールドの一覧、スキーマの注意点（styling.background は必須ですが現在は使用されていないこと、header.links[] に links: [] が必要なこと）、ヘッダー／フッターリンクの ContentRef 形式、条件付きリンクのパターンについては、references/customization-recipes.md の「Field cheatsheet」とシナリオ 4～5 を参照してください。カスタムロゴ、カスタムフォント、セマンティックカラー、フッターロゴ、高度なカスタマイズなどの Premium および Ultimate 機能は、無料サイトでは拒否されます。適切に対処してください。REST 経由の場合は、正確なエラーレスポンスについて references/api-cheatsheet.md を参照してください。

references/customization-recipes.md には、カラーとファビコンのみの最小限のブランド設定、ロゴとフォントを使った完全なブランド設定、ダークモードのみと切り替え機能、AI アシスタントと推奨プロンプトを有効にする設定の実例があります。

参考にできる、実際のプロジェクトで使用されている完全なペイロードとして、このスキルに同梱されている本番サイトのカスタマイズエクスポート references/example-site/customization.json があります。実際にすべてのフィールドがどのように組み合わされるかを把握するには、抽象的なスキーマを読むより、これを確認するのが最も手早い方法です。新しいサイトにそのまま貼り付けず、構造やフィールドの選び方のモデルとして利用してください。

構造レスポンス（セクション、セクショングループ、多言語サイトスペース）の実例については、併せて references/example-site/structure.json を参照してください。

Git Sync の引き継ぎ

ここは、洗練された対応が求められる部分です。リポジトリがプッシュされ、サイトが存在する状態になったら、スペースごとではなく、サイト全体について明確な引き継ぎ情報を一つ作成してください。ユーザーに必要な情報は次のとおりです。

1. リポジトリの URL とブランチ名（通常は main）
2. サイトの Project directory — gitbook-docs.yaml が置かれている場所（大規模なモノレポでない限り、空欄またはルート）
3. 最初の同期方向 — この時点ではリポジトリが正となるため、ほとんどの場合 GitHub → GitBook（または GitLab → GitBook）
4. コンテンツのマッピング — 各スペースのタイトルとディレクトリの組み合わせ（例：Guides → ./guides、API Reference → ./api-reference）

references/git-sync-handoff.md には、ユーザーに提示するための記入式テンプレートがあります。1 回接続し、同じ手順で全スペースをマッピングしてください。長い文章を並べたり、スペースごとに繰り返したりせず、番号付きリストを一つだけ表示してください。特定のスペースを独立したリポジトリ／ブランチに切り出す必要がある場合に限り、2 つ目の引き継ぎ情報を追加してください。詳細は同ファイルの「When a space needs its own repo or branch」を参照してください。ユーザーが作業を終えたら、完了したことを確認してください。その時点で、各スペースの同期状態をプログラムから確認できます（サイト全体のステータスエンドポイントはまだないため、内部ではスペースごとに確認します）。

よくある間違いと回避方法

• PAT を Claude が書き込むファイルに入れないでください。 必ず環境変数から読み取ってください。
• コンテンツのソースを黙ってすり替えないでください。 ユーザーが指定したリポジトリやフォルダーを読み取れない場合（非公開リポジトリは存在しないリポジトリと同じく 404 を返すことに注意してください）は、作業を止めて確認してください。似たような公開リポジトリを使って作業を進めてはいけません。「ビルド前にコンテンツのソースを確認する」を参照してください。
• Git Sync をプログラムで設定しようとしないでください。 どのトランスポートでも UI からしか設定できません。必ず UI への引き継ぎを行ってください。（installGitSyncProviderOnTarget は API に存在しますが、OAuth の手順は省略できず、まだ MCP 経由では公開されていません。便利そうだからといって、引き継ぎを迂回しないでください。）
• Git Sync をスペースごとに個別に引き継がないでください。 サイト全体での Git Sync がデフォルトです。1 つの接続と、すべてのスペースを対象にした 1 回のコンテンツマッピングで済みます。特定のスペースに独立したリポジトリやブランチが必要な場合に限り、スペースごとの Git Sync を使用してください。
• カスタマイズのペイロード全体を記憶から貼り付けないでください。 現在の状態を取得し、変更を加えてから、完全な結果を書き戻してください。スキーマは進化するため、この方法ならバグも減らせます。
• コンテンツのセクションごとにスペースを作成しないでください。 スペースは独自の URL スラッグ、同期、設定を持つ大きな単位です。小分けには、スペース内のページやフォルダーを使用してください。
• ユーザーが急いでいる場合でも、構成の計画と確認の手順を省略しないでください。 公開済みサイトの再構成は大変です。
• SUMMARY.md を過度に書式設定しないでください。 GitBook のパーサーは厳格です。write-docs のルールに従ってください。
• 変更リクエストの編集を、リンクを 2 つ揃えずに終わらせないでください。 「変更リクエストのプッシュ後：リンク 2 つが必須」を参照してください。CR の差分リンクだけでは回答として不十分です。

参照ファイル

• references/api-cheatsheet.md — このスキルで使用する API 呼び出し一式。curl 形式のリクエスト本文と想定されるレスポンスを記載しています
• references/site-structure-design.md — 生の入力からスペース／セクション／ページの計画を作成するためのヒューリスティックと具体例
• references/migration-from-other-platforms.md — 移行前の確認、ソースプラットフォームのマッピング（Mintlify、Docusaurus、GitBook v1、RTD）、アンカーページの方針、フォーマットの調整、内部リンクの一括確認。移行ビルドを行う前に必ず読んでください。
• references/block-ecosystem.md — コンテンツの状況に応じて使用する GitBook ブロックを、判断表と具体例（Updates、Mermaid、OpenAPI の自動生成、レイアウトフラグ、カードテーブル、条件付きコンテンツ、インクルード、変数）とともに説明しています。複雑なページを生成する前に必ず読んでください。
• references/cross-space-links.md — Markdown 内のスペース間リンクを処理するためのセンチネルと解決のワークフロー、および動作する置換スクリプト
• references/git-sync-handoff.md — ユーザー向け Git Sync 設定手順のテンプレート。サイト全体での設定を優先し、スペースごとの設定は文書化された代替手段として扱います
• references/customization-recipes.md — よくあるシナリオの具体的なブランディングペイロード
• references/example-site/ — 実際の本番環境を想定した GitBook サイトリポジトリの抜粋スナップショット（約 150 ファイル）。Markdown、SUMMARY.md、.gitbook/ 設定を含みます。最初に中の PRUNE-NOTES.md を読んでください。残されているもの、削除されたもの、パターンごとの重要なファイルが記載されています。
• references/example-site/customization.json — このサイトからエクスポートしたカスタマイズ。実際の完全なブランディングペイロードの例です
• references/example-site/structure.json — 構造のエクスポート。セクション、セクショングループ、複数言語のサイトスペース（Git 同期された英語版＋自動翻訳）を示しています