サイトを設定する

GitBookのドキュメントサイト全体をエンドツーエンドで作成・保守する — ソースコンテンツからサイト構造を設計し、モノレポ構成でGitリポジトリを足場作成し、GitHub/GitLabのリモートを設定し、推進する

GitBookドキュメントサイト全体を作成・維持するためのスキル。 write-docs が1つのページ内の内容を扱うのに対し、このスキルはページの周辺すべて、すなわち構造設計、リポジトリの足場構築、GitBook API、ブランディングを扱います。2つのスキルを併用してください。このスキルは write-docs ページコンテンツを生成または編集する必要があるときは常に呼び出します。

GitBookとのやり取り方法

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

「MCP優先」は転送手段に関するものであり、コンテンツに対してGit Syncを回避するという意味ではありません。 MCPは変更リクエスト用のコンテンツプッシュツール（updateChangeRequestContent）を公開しており、接続されていればいつでも使いたくなります。しかし、すでにGit Syncが設定されているスペースでは、小規模で対象を絞った編集以外については、ローカルリポジトリ内のファイルを編集し、Git SyncにGitBookへの反映を任せる方法が引き続き推奨されます。スペースがGit同期されていない、環境にローカルチェックアウトがない、または変更リクエストを開くことが適切なほど編集が小規模である場合は、代わりに変更リクエストのプッシュ（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の別の読み取り専用「published docs」MCPサーバーとは別で、そこでは既に公開済みのコンテンツしか扱えません。
REST API (https://api.gitbook.com/v1）— MCPが接続されていない場合、またはMCPで扱えないことを行う際の代替手段です。必要です GITBOOK_TOKEN を各リクエストのBearerヘッダーとして付ける必要があります。

同じ個人アクセストークン（https://app.gitbook.com/account/developer から取得）が、両方でBearerトークンとして使えます。MCPはさらに、トークン貼り付けよりも使いやすい代替としてOAuthもサポートしています。

もしトークンが必要になったら （REST API経路、またはOAuthなしのMCP）の場合、セッション開始時に次で確認してください：

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

もし GITBOOK_TOKEN が設定されていない場合は、ユーザーに直接依頼してください：

GitBookの個人アクセストークンが必要だと伝えてください。 https://app.gitbook.com/account/developer で作成するよう案内してください。
トークンを会話に貼り付けてもらうよう依頼してください。直ちに環境変数としてエクスポートし（export GITBOOK_TOKEN=<pasted value>）、応答でそれを繰り返し表示しないでください。
トークンが環境内に存在することが確認されるまで、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も依然として存在しますが、現在は例外です。特定のスペースに独立したリポジトリまたはブランチが必要な場合（例：公開ドキュメントリポジトリには置けない非公開スペース）にのみ使用してください。

つまり、最もクリーンなエンドツーエンドのフローは常に次のとおりです：

ClaudeはローカルでGitリポジトリをモノレポとして足場構築します（スペースごとに1ディレクトリ）。理想的には、 gitbook-docs.yaml で各スペースをそのディレクトリに対応付ける設定をあらかじめ作成し、ツールが許せばリモートへプッシュします
Claudeは、作成可能なサイト、セクション、および空のスペースを作成します
ユーザーはGitBookで、サイトをリポジトリ/ブランチに接続し、スペースとディレクトリの対応を確認するという、短く十分に手順化されたUI操作を1回行います — スペースごとに1回ではありません
Claudeはブランディング/カスタマイズを適用します

ステップ3におけるユーザーの役割は避けられませんが、決して意外なものにしてはいけません。明確で、そのままコピー＆ペーストできる手順を生成してください。参照： references/git-sync-handoff.md.

ユーザーが明示的にGit Syncを望まない場合は、コンテンツインポートのパス（コンテンツのインポートとテンプレートの適用）にフォールバックしてください。これについては以下で簡単に、また references/api-cheatsheet.md.

最初に収集すべき入力情報

これらが判明するまで足場構築を始めないでください。不足があれば推測するのではなく、焦点を絞った質問を1回してください。（認証は別途処理します。上記の「GitBookとの通信方法」を参照してください。）

組織 — ユーザーの組織を一覧表示し、 そのリストをユーザーに表示してから、対象がどれかを名前で確認するよう求めます。組織が1つしかない場合でも実施してください。最初に1回確認するだけで、誤った場所にサイトを作成することへの安価な保険になります。選択した organizationId をセッションの残りの間保存し、以降の手順を説明する際はUUIDではなく組織のタイトルで参照してください。
サイト計画と公開範囲 — デフォルトを type: site 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リファレンスのスペースは builtin:openapi のSUMMARYエントリ1つと、リソースごとの1段落の概要READMEだけで済みます。手作業でエンドポイントページを作成するより劇的に少ない作業で、ずれることもありません。 references/block-ecosystem.md 、 references/api-cheatsheet.md でワークフローを確認してください。 手作業で作成するエンドポイントページをデフォルトにしないでください — それはほとんど常に誤った選択です。
ブランディング — 最低限、プライマリカラー（16進数）。任意：ロゴURL（ライト＋ダーク）、ファビコン、フォントの選択（またはGitBookのデフォルトのいずれか）、ヘッダーリンク、フッターテキスト/リンク、テーマプリセット（clean, muted, 太字, gradient）。Ultimateサイトでは、AIアシスタントのスタータープロンプト（訪問者が尋ねそうな短い質問を3～5個）も検討してください。
サイト構造 — サイトスペースではなくセクションです。サイトに複数のスペースがある場合は、 セクションリスト をユーザーと明示的に計画してください。各セクションにはタイトル、Font Awesomeのアイコン名、説明があります。セクションのアイコンと説明は、訪問者に見える主要なナビゲーション要素であり、最初に収集すれば後からセクションごとに更新する手間を省けます。例： [{title: "ガイド", icon: "book-open", description: "概念とチュートリアル"}, {title: "APIリファレンス", icon: "code", description: "REST APIとSDK"}, {title: "変更履歴", icon: "clock-rotate-left", description: "更新とリリースノート"}].
Gitリモートの希望 — GitHub、GitLab、またはローカルのみ。 gh または glab がインストールされているか確認してから その前に 尋ねてください。どちらのツールも利用できない場合は、 そのことを明示してください し、2つの選択肢を提示します。(1) ローカルでコミットし、「リモートを作成してプッシュする」手順をユーザーへの引き継ぎの先頭に置く、または (2) ユーザーにツールをインストールしてもらう。伝えずにローカルのみをデフォルトにしないでください。リモートも手順もないリポジトリが残ってしまいます。
サイトの構成 — 単一スペースか複数スペースか。複数スペースのサイトでは、 セクション を使用してナビゲーション内でスペースをグループ化します。コンテンツに明確に異なる対象者がいる場合（例：ユーザードキュメント＋APIリファレンス＋変更履歴）には、これが適切な選択です。サイトスペースを直接使用するのは翻訳バリアントに限ってください。 references/api-cheatsheet.md.

構築前にコンテンツソースを検証する

ユーザーがコンテンツの種（リポジトリ、フォルダ、またはドキュメントサイトURL）を指定したら、 その前に 構造を設計したり何かを足場構築したりする前に、それを実際に読み取れることを確認してください：

ソースを解決して表示する。 これから読み取る対象（リポジトリURLとブランチ、フォルダパス、またはサイトURL）を正確に明示し、ユーザーが正しい対象か確認できるよう、その最上位の内容（短いファイルまたはページの一覧）を表示してください。
アクセスできない場合は、停止してその旨を伝えてください。 Gitホストは 非公開リポジトリに対して404を返します — 「リポジトリが存在しない」と区別できません。ユーザーが指定したリポジトリに対する404またはクローン失敗はすべて、 非公開である可能性があるものとして扱ってください。失敗した内容をユーザーに伝え、コンテンツにアクセス可能にする（ローカルクローン、アーカイブ、認証済みの gh/glab、公開ミラー）か、URLを修正するよう依頼してください。リポジトリに到達不能と宣言する前に、認証済みの gh/glab CLIが利用可能か確認してください。
ソースを代用してはいけません。 同名または類似名のリポジトリやサイトを検索、推測、フォールバックしてはいけません。たとえ同一に見えてもです。誤ったソースからドキュメントサイトを構築することは、質問のために中断するよりはるかに悪い結果になります。ソースの変更にはユーザーの明示的な承認が必要です。

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

サイト作成、スペース作成、セクション追加、サイトスペースの接続、カスタマイズ変更はすべて、 組織内の全員にすぐ見える オブジェクトを作成または変更し、クリーンアップにも実際の労力がかかります。重大な操作として扱ってください。

ルール： これから起こることを正確に1画面でプレビュー表示し、明示的な「はい」を得る前に、状態を変更する操作を決して行わないでください。

良いプレビューは短く具体的です：

次の操作を実行します。組織： Acme Inc (org_abc123):
サイトを作成 「Acme Platform Docs」 （type: site、plan: ultimate、visibility: public）
空のスペースを3つ作成： ガイド, API リファレンス, 変更履歴
ガイドをデフォルトセクションとして追加し、APIリファレンスと変更履歴のセクションを作成
続行しますか？（はい/いいえ）

悪いプレビューは曖昧（「これからサイトを作成します」）であるか、説明の壁に埋もれています。ざっと確認しやすいものにしてください。

同じルールは破壊的な操作、つまりサイト、スペース、セクション、カスタマイズのオーバーライドの削除にも適用されます。ただし、さらに曖昧さをなくしてください（「これによりサイト Acme Platform Docs とその3つのスペースが削除されます。スペースとサイトは7日間復元可能ですが、その後は完全に削除されます。確認しますか？」）。

ユーザーが構造設計のステップで複数手順の計画をすでに確認している場合、その計画内の個々の操作ごとに再度尋ねる必要はありません。ただし、計画内の何かが変わる場合（スペースの追加、可視性の変更）は再確認してください。

読み取り専用操作（取得または一覧表示）には確認は不要です。

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

このスキル（または write-docs、このスキルがページ執筆を委任するもの）が、MCPの updateChangeRequestContent/create_change_request/submit_or_merge_change_request 厳選ツール、 ）に置き換え、輸送方式が一致しないという理由で手順を飛ばさないこと。、またはREST相当の機能を介して変更リクエストでコンテンツをプッシュする場合、その編集は 完了していません 。毎回、以下の両方をユーザーに報告するまで完了とは見なされません：

変更リクエストの差分/エディタリンク (urls.app）— GitBookアプリで変更を確認するためのリンク。
サイトのプレビューリンク — 変更が適用されたレンダリング済みのドキュメント。これには別の検索が必要です。サイトURLは公開サイトの場合 Site オブジェクト（urls.published にあり、そうでない場合は urls.preview）にあります。変更リクエストオブジェクトにはなく、必ず /~/changes/<number>/ を末尾に追加し、APIが返す末尾のスラッシュは除去してください。このセグメントがないと、リンクはサイトの 現在の コンテンツを表示し、この変更リクエストではなくなります。読み込みは成功しますが、誤った内容が表示されます。

これは上記の確認ゲートと同等の厳格なルールです。時間があれば追加する程度の親切ではありません。 write-docsの「変更リクエストが関係する場合は常に2つのリンクが必須」と、 cr-create スキルの「プレビューリンクの提示」で、正確な解決手順を確認してください（MCP： list_sites → サイトを見つける get_site_structure/getSiteById または各サイトのサイトスペース → を介した を .urls.preview；REST：同等の連鎖した GET 呼び出し）。スペースが公開済みサイトに接続されていない場合は、説明なしに差分リンクだけを提示するのではなく、その旨を明確に伝えてください。

サイト構造の設計

ファイルを書いたりGitBookに何かを作成したりする前に、構造を決定してユーザーに確認してください。弱い構造は、ドキュメントサイトが定着しない最大の理由です。

このステップの出力は小さな計画で、理想的には次の3項目です：

スペース一覧 — 一貫したコンテンツのまとまりごとに1スペース。少数に保ってください（通常は1～4スペース）。スペースはナビゲーションとGit Syncの単位なので、1つの対象者向けコンテンツを複数スペースに分割しないでください。
セクションのグループ分け （複数スペースの場合）— セクションはサイトナビゲーションの最上位区分で、たとえば「製品」/「開発者」/「リソース」です。セクションには1つ以上のスペースを含められます。
スペースごとのページツリー — フォルダとページ、および各ページの1～2文の要約。深さはコンテンツに合わせるべきですが、浅いツリー（1～2階層）が通常は最適です。

生の入力から構造計画へ進むための完全なヒューリスティックは、 references/site-structure-design.md にあります。重要でないサイト以外で初めてこれを行うときは読んでください。 ファイルを足場構築する前に、必ず計画をユーザーに示し、明示的な承認を得てください。 後での再構成はGit内では安価ですが、サイトが公開・インデックス化された後では高コストです。

ユーザーが1つにまとめた指示を与えた場合の確認に関する注意：たとえば、 「構造を計画してから足場構築する」 のようなプロンプトでは、ゲートを飛ばしたくなります。飛ばしてはいけません。計画を明確で確認しやすいブロックとして提示し、「はい」を待つか、プロンプトが非常に明示的で既に足場構築を始めた場合は、計画で決定した内容を明示し、方向修正のための簡単な機会を1回設けてください（「何か違っていれば、先に進む前に知らせてください。やり直します」）。重要なのは、ユーザーが計画を目にすることです その前に ユーザーが20個の生成済みファイルを前にしているときではなく、やり直しがまだ安価なうちに。

リポジトリの足場構築

構造が合意されたら、単一スペースのサイトであってもモノレポとしてリポジトリをレイアウトしてください。これは一貫性があり、将来にも対応できます。各スペースは、独自の README.md （ホームページ）と SUMMARY.md （目次）を含むディレクトリです。任意で、スペースごとの変数と再利用可能なコンテンツブロック用の .gitbook/ フォルダ、さらに任意で高度な同期設定用の .gitbook.yaml を置けます。

3スペースのサイトのレイアウト例：

my-docs/
├── .gitignore
├── README.md                    # リポジトリレベルのREADME（スペースのホームページではない）
├── guides/                      # スペース1
│   ├── README.md                # スペースのホームページ
│   ├── SUMMARY.md
│   ├── .gitbook/
│   │   └── vars.yaml            # 任意：スペースレベルの変数
│   ├── getting-started/
│   │   ├── installation.md
│   │   └── quickstart.md
│   └── concepts/
│       └── ...
├── api-reference/               # スペース2
│   ├── README.md
│   ├── SUMMARY.md
│   └── endpoints/
│       └── ...
└── changelog/                   # スペース3
    ├── README.md
    └── SUMMARY.md

このレイアウトについて、人がよくつまずく点をいくつか説明します：

.gitbook.yaml は任意です。 GitBookは、デフォルトの慣例である README.md + SUMMARY.md スペースごとでも問題なく動作します。 .gitbook.yaml を追加するのは、ルートをオーバーライドする、リダイレクトを定義する、またはその他の非デフォルト操作が必要な場合だけです。付属のサンプルサイト（references/example-site/）には .gitbook.yaml ファイルが1つもありませんが、完全に動作します。
.gitbook/vars.yaml には、ページがインラインで参照できるスペーススコープの変数を格納します（例： support_email: support@evolve.com は次のように参照されます： {% vars.support_email %}）。多くのページに現れる値に便利です。
.gitbook/includes/<name>.md には再利用可能なコンテンツブロックを格納します。多数のページに {% include "...persona-switcher" %}で埋め込むスニペットです。定型文をコピー＆ペーストする代わりに使用してください。
スペースディレクトリ名（例： guides/）は、サイト全体のGit Syncを設定するときにユーザーがそのスペースを コンテンツのマッピング で対応付ける対象です。サイトの「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

[My Productドキュメントサイト](https://docs.example.com)のソース。各最上位フォルダ
は個別のGitBookスペースです。設定後、編集はGit Syncを通じて双方向に反映されます。

1つの .gitignore では、OSの不要ファイルとエディタ設定をリポジトリから除外する必要があります。妥当なデフォルト：

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

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

SUMMARY.mdの生成 — ナビゲーションを収集し、フォルダから推測しない

最も一般的な足場構築のミスは、ファイルツリーをたどってそこからSUMMARY.mdを出力することです。つまり、READMEを先頭に置き、他のすべてのファイルをREADMEの子としてインデントします。これは意気消沈するナビゲーションを生みます。すべてのページが「ホームページの子」になり、フォルダ名は読者にとって意味があるかどうかにかかわらずグループ名となり、情報アーキテクチャはユーザーのメンタルモデルではなくファイルシステムを反映します。

正しいパターンを順に示します：

構造設計中に、ユーザーから希望するナビゲーションを収集します。 各スペースの最上位ページと名前付きグループを列挙するよう、明示的に尋ねてください。ここでフォルダ名を実際のナビゲーションに一致させ、ユーザーは「実際には認証をConceptsの下ではなく最上位ページにしたい」と伝えられます。
合意したナビゲーションに合わせてフォルダをレイアウトし、その逆にはしないでください。 ユーザーがスペース内に「はじめに」「概念」「チュートリアル」という3つのグループを望む場合、スペースディレクトリにはそれらの名前（スラッグ化したもの）の3つのサブフォルダがあり、それぞれに独自のページがあります。散在するサブフォルダから4つ目のグループを自動抽出しないでください。
ユーザーが合意した明示的な形でSUMMARY.mdを書きます。 GitBookが認識する文法：
```
# 目次

* [スペースのホームページ](README.md)
* [最上位ページA](top-level-a.md)
* [最上位ページB](top-level-b.md)

## 最初のグループ

* [グループ内のページ](first-group/page.md)
* [別のページ](first-group/another.md)

## 2番目のグループ

* [ページ](second-group/page.md)
```
重要な形式ルール：
- README.mdは先頭の独立した行に置き、兄弟項目にします。親項目にはしません。他の最上位ページも兄弟項目として続けます。
- ## グループ名 の見出しでグループを導入します。 グループ内のページは見出しの直下にフラットな箇条書きで置きます — しません READMEの下にインデントしません。
- 機械的な「README.md」＋その下にすべてをネストする構造は避けてください。* これによりナビゲーション全体がホームページの下の1つのツリーに折りたたまれ、サイドバーではすべてのページがホームページのサブページに見えてしまいます。
- グループ名はフォルダ名ではなく、ユーザーから取得します。 「concepts/」はフォルダのスラッグにできますが、より明確であればグループ見出しは「仕組み」とすることができます。
- ページごとに箇条書きは1つで、追加の書式は使いません。 太字やSUMMARY内の説明は不要です。それらはページのフロントマターに記載します。
特別なケースのパターン 通常の箇条書きではないもの：
- 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: フィールド。アイコンは Font Awesome の名前で、 fa- プレフィックス（例： book-open, bolt, house, コード, puzzle-piece, id-card, circle-dollar-to-slotを含みません）。名前を勝手に作らないでください。Font Awesome のカタログから選んでください。このサンプルサイトでは、ほぼすべてのページのフロントマターでこれらが使われています。
レイアウトフラグ を含む layout: width: wide （使いどころは限定してください。マーケティング風のランディングページ、Updates タイムラインのある変更履歴ページ、複数カラムのブロックや本当に幅広の表があるページなどに使います。 すべての Space のホームページで wide をデフォルトにしないでください — GitBook のデフォルト幅はドキュメント向けに適しており、カードテーブルのあるドキュメント用ランディングページも含めて正解です。wide はヒーロー型のマーケティングレイアウト向けで、通常のドキュメント向けではありません。） カバー: 、画像、およびページごとの表示フラグ（title.visible, tableOfContents.visibleなど）。
SUMMARY.md 文法。 厳格な形式 — 1 ページにつき 1 つの箇条書き、任意の ## グループ名 見出し、余計な装飾なし。さらに、仕様からエンドポイントページを自動生成するための特別な type: builtin:openapi 構文があります。
リッチブロック — タブ、ヒント、ステッパー、カラム、カードテーブル、展開ブロック、埋め込み、 {% if visitor.claims... %}を使った条件付きコンテンツ、OpenAPI ブロック、 Updates ブロック（変更履歴）、再利用可能なコンテンツの include。
GitBook 風 Markdown の違い を CommonMark と比べたもの。

ここでそれを再発明しないでください。付属の references/example-site/ は、慣用的なコンテンツがどう見えるかを知るための、実務上いちばん良い参照資料です。

適切なブロックを選ぶ — デフォルトではなく、能動的に

よくある失敗パターン: Claude がドキュメントを生成するが、動くものの、すべてをプレーン Markdown で済ませてしまい、GitBook サイトを本物の製品のように見せるリッチブロックを取り逃がす。 このスキルは、特殊なブロックを積極的に使うべきであり、裸の文章と箇条書きに逃げてはいけません。体得すべき具体的パターン:

変更履歴 → {% updates %} ブロックを {% update date="..." tags="..." %} エントリで使います。RSS を自動生成し、タグ（ .gitbook/tags.yamlで定義）をサポートします。 ## YYYY-MM-DD 見出しは書かないでください — 形が違います。
API エンドポイント参照 → OpenAPI 仕様を 1 回アップロードし、 type: builtin:openapi を使って SUMMARY.md からページを自動生成します。エンドポイントページを手作業で書かないでください — ずれてしまいますし、そもそも仕様が唯一の正です。ユーザーが仕様を持っていない場合は、文章ベースにするより先に最小限の仕様を下書きする提案をしてください。
状態機械、フロー、シーケンス、簡単なアーキテクチャ → ```mermaid は fenced ブロックで表現します。ASCII で箱と矢印を描かないでください。Mermaid がサポートされており、きれいに描画され、スクリーンリーダーにも優しいです。
Space のホームページ → 通常のドキュメントのランディングには GitBook のデフォルトレイアウトを使ってください（TOC を表示、デフォルト幅）。 layout: width: wide を使うのは、本当にマーケティング風のページだけです — ヒーロー画像、非常に大きいカードグリッド、複数カラムのダッシュボードレイアウトなど。デフォルトはドキュメント向けに正しいです。
「自分の道を選ぶ」系コンテンツ → カードテーブル（<table data-view="cards">）。HTML は冗長ですが、見た目の成果はどの Markdown の代替よりも優れています。
左右並びのイントロパターン → {% columns %} ブロック。2 カラムを 50/50 にするのが標準です。
繰り返しの定型文（3 か所以上） → .gitbook/includes/<name>.md + {% include "..." %}.
繰り返しのリテラル（環境 URL、サポートメール、バージョン固定） → .gitbook/vars.yaml + <code class="expression">space.vars.<name></code>.
多言語のコードサンプル → {% tabs %} ブロック。
順序付き 3 ステップ以上の手順説明 → {% stepper %} ブロック。

ブロックごとの完全ガイドは、実行例と smell-vs-fix の判定表つきで references/block-ecosystem.md. にあります。非自明なページを生成する前に読んでください

スペース間リンク

複数 Space のサイトでは Space 間リンクが必要です — それが、サイトをバラバラのマニュアルの寄せ集めではなく、1 つにつながった製品のように感じさせる方法です。 それを避けるためにコンテンツを重複させないでください。そして、削除もしないでください。 これは GitBook の第一級機能です。違いは、正しく描画するために本物の Space ID が必要で、ID はサイト作成後にしか存在しないことだけです。

Markdown でのパターンは、単に対象 Space の GitBook URL への通常のリンクです:

概念面については、[Authentication concept page](https://app.gitbook.com/s/<spaceId>/concepts/authentication) を参照してください。

GitBook は https://app.gitbook.com/s/<spaceId>/<path> をレンダリング時に解決します。カスタムドメインに関係ありません。内部的にはこれらは ContentRefPage または ContentRefSpace で、space ID が設定された content reference です。Markdown では単なる URL として表示されます。

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

スキャフォールディング中は、Space 境界をまたぐリンクについては、 XSPACE_を前置したシンボルの Space ID を使って cross-space link を書きます。計画中の Space ごとに 1 つずつです。構造計画の space slug を接尾辞として使ってください:
```
[Authentication concept page](https://app.gitbook.com/s/XSPACE_GUIDES/concepts/authentication) を参照してください。
完全な参照は、[API Reference](https://app.gitbook.com/s/XSPACE_API/) を参照してください。
```
これらは存在しない GitBook Space への有効な Markdown リンクです — パーサーを壊さず、grep しやすく、Git 経由でもきれいに往復できます。
Space 作成後、各新規 Space の本物の ID を得たら、すべての Markdown ファイルをたどって XSPACE_<KEY> を実際の Space 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/*')
```
解決結果をコミットして push します 。GitBook は Git Sync 経由でそれを取り込み、次回のレンダリングでリンクが解決されます。

きれいに実装するために、 cross-space-links.yaml をリポジトリのルートに置き、シンボルキーと Space ID の対応を記録してください。これは作成後に生成します。そうすれば、誰かが再実行しても解決スクリプトを再現可能にできます。アンカーリンク、ページ固有リンク、サンプル解決スクリプトを含む完全なパターンは references/cross-space-links.md.

これはどこに書き込むか: スキャフォールド（シンボル付き）、Space をまたいで生成していく Markdown コンテンツ、そして作成後の解決ステップです。実際の app.gitbook.com/s/<id>/... リンクをスキャフォールディング中に書こうとしないでください — ID はまだ存在せず、推測しても壊れたリンクになるだけです。

サンプルコンテンツの探し方

references/example-site/ は 整理済みスナップショット で、このスキルに同梱されている本番風の GitBook サイトのものです。元のサイトは 12 Space（ホーム、3 つのプロダクト Space、開発者 API の 3 つのバージョン、3 つのガイド Space、パートナー、変更履歴、さらに外部コンテンツの connections/ tree）で、約 200 のコンテンツファイルがありました。同梱スナップショットは、ファイル数制限内に収めるため約 150 に絞っています。

を読んでください references/example-site/PRUNE-NOTES.md まず — 何を残し何を削ったかを正確に説明し、特定のパターンを読むための重要度の高いファイルも列挙しています。要点は次のとおりです:

各 Space の完全な構造の骨格は維持されています — README.md, SUMMARY.md, .gitbook/vars.yaml, .gitbook/includes/.
developers/v2/ が、正規のサンプルとして完全に残されています。 developers/v1/ （旧版）と developers/v3/ （beta）は削除されました — バージョン固有の内容差分を除けば v2 と構造上は同一だったからです。複数バージョン API ドキュメントのパターンは PRUNE-NOTES.md に記載されており、 structure.json.
connections/ で見られます — 各サブフォルダ（blog/, community/, youtube/）は index.html に加え代表記事を 1 本ずつ保持しており、メタデータのパターンを学習しやすくしています。
customization.json 、 structure.json は、削除された Space やページを含め、元のサイト全体を説明する完全な API エクスポートです。各 Space 内の SUMMARY.md ファイルも元のツリーを記述しており、その中の一部リンクは削除済みページを指しますが、それは想定どおりです。

注目すべきファイルは、 示したいパターンごとに整理されています:

パターン

読むファイル

Updates ブロック + タグ

changelog/README.md + changelog/.gitbook/tags.yaml

builtin:openapi SUMMARY パターン

developers/v2/SUMMARY.md （fenced YAML の箇条書きを見てください）

Mermaid 図（flowchart、sequence）

products/payments/concepts/payment-lifecycle.md, developers/v2/identity-api/README.md

レイアウト width: wide + cover image

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

再利用可能なコンテンツ include

home/.gitbook/includes/persona-switcher.md

.gitbook/vars.yaml 変数

任意の Space の .gitbook/vars.yaml

まとめられた SUMMARY.md（ ## Heading)

任意の Space ごとの SUMMARY.md ファイル

同梱スナップショットに表現されていないパターンが必要なとき（例: legacy/beta のバージョン付き API Space を並べて置く、外部コンテンツの記事カタログ全体など） 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 つの有効な道があります:

ローカルのみのリポジトリ + handoff で手動の remote 手順。 ローカルでコミットし、handoff に「Step 0」を残して次のように書いてください: 「あなたのマシンで、 <name>、次に git remote add origin <url> && git push -u origin main という名前の非公開 GitHub または GitLab リポジトリをこのディレクトリから作成してください。」 これは GitBook の UI 手順より前に置いてください — Git Sync が接続するには、先にリポジトリを push しておく必要があります。
ユーザーに gh または glab. のインストールを促してください。

こっそりローカルのみをデフォルトにしないでください — remote のないリポジトリと、その追加方法の説明がないのは、Git Sync をつなごうとしたときにユーザーが踏む地雷です。

移行とコンテンツ品質

実際のビルドの多くは新規作成ではありません — 既存のドキュメントプラットフォーム（Mintlify、Docusaurus、ReadTheDocs、古い GitBook）からの移行、または既存 Markdown の再構成です。これらには「新しいサイトを作る」とは別の、独自の規律があります。ここを誤ると、 見た目は ドキュメントサイトなのに、読んでみると機械出力のようなものを作ってしまいます。

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

再構想する前に、元をそのまま写してください。 ユーザーが既存の公開ドキュメントサイトを持っている場合は、レンダリング済みのランディングページを取得して、ホームページのコンテンツを生成する前に見てください。現在の IA が仕様であり、ユーザーがそうした理由は、Markdown のフォルダだけでは普通見えません。元のサイトにすでに正解があるのに、カードグリッド、ヒーローブロック、「新着情報」セクションをゼロから発明するのは、最もよくあるコンテンツ品質の失敗パターンです。

一括エクスポートは、完全なコンテンツソースとは限りません。 Mintlify の llms-full.txt、ReadTheDocs の HTML スクレイプ、そして同様の AI フレンドリーなエクスポートは、見えているコンテンツをしばしば削ります（カスタムコンポーネントが生のマークアップに展開される、AI プロンプトブロックがインライン展開される、API テーブルからパラメータ名が消えるなど）。一括変換のあと、レンダリング済みページを元サイトと照合し、コンテンツが欠けている箇所を指摘してください — エクスポートが物語のすべてだとは思わないでください。

アンカーページを作り、全部のページを作らない。 280 ページを移行するからといって、280 ページすべてを GitBook 流で手作業作成するわけではありません。正しいやり方は、長い尾を一括変換し、その後、ホームページ、各 Space のトップランディング、目玉のハウツーなど 4〜6 枚のアンカーページを意図的に作り直し、フルのブロックエコシステムを使うことです。残りは反復的に標準へ引き上げればよいです。

フォーマット調整は文書化された手順です。 素朴な Markdown 変換では、外部コンポーネントタグ、不正な code fence、壊れた内部リンクなどの痕跡が残ります。一括変換のあと、最初の commit の前にクリーンアップ工程を実行してください — 未対応コンポーネントを削除し、fence を正規化し、 /docs/... のパスを GitBook URL か相対パスに書き換えます。これを飛ばすと、ほぼレンダリングはするが、壊れたリポジトリになります。

存在しないフロントマターを自動生成しないでください。 元にアイコンがない場合は、URL スラッグからアイコンを自動選択しないでください — ずれた cog アイコンだらけになります。元に説明文がない場合はフィールドを空にしてください。 Source: <url> で埋めないでください（そのテキストはサイドバーのプレビューと検索に漏れます）。

API 参照は OpenAPI ファーストで。 移行先サイトに API リファレンスがあり、OpenAPI 仕様を取得できる（またはコードベースから生成できる）なら、参照用 Space 全体を builtin:openapiで処理してください。70 ページの手変換参照より、3 ファイルの自動生成版のほうがほぼ常に優れています。

内部リンク変換は一括処理であり、ページごとの話ではありません。 構造がわかったら、すべての Markdown ファイルをたどって /docs/... リンクを、相対 .md パス（同一 Space 内）か https://app.gitbook.com/s/<spaceId>/<path> URL（Space 間）に書き換えてください。これをページごとにその場しのぎで行うとリンクが不整合になります。slug-to-path の manifest を使って 1 回の sweep として行うほうが、はるかに信頼できます。

コンテンツを再生成する補助スクリプトには注意してください。 コンバータや SUMMARY 生成器を使うなら、デフォルトでは冪等にしてください。既存ファイルはスキップします。手作業で調整したホームページを上書きする 2 回目の実行は地雷です。 rm -rf <space>/ を、手編集されたコンテンツが入っている可能性のあるディレクトリで実行してはいけません。再生成が必要なら、 <space>/_generated/ に出力してから、マージするか diff を取ってください。

GitBook にサイトをビルドさせる

以下の手順はエンドポイント呼び出しではなく結果として説明しています — 上で「GitBook とどうやって話すか」で選んだ任意の transport を使ってください。REST API ルートでは、各手順の正確なエンドポイント、リクエスト本文、期待レスポンスは references/api-cheatsheet.mdにあります。呼び出しの前に必ず読んでください — スキーマは微妙です（特に customization）。MCP ルートでは、対応するツールが同じ手順をカバーします — REST パスを調べるのではなく、それぞれのスキーマを読んでください。

新しいサイトの標準シーケンス

アクセスを確認して組織を見つける: 認証されたユーザーを確認し、次に組織一覧を取得します。
サイトを作成する とともに {title, type, visibility, spaces?}. Ultimate をデフォルトにする (type: "site"; プラン階層は、作成後にサイト上で、または組織の請求設定経由で設定されます）。ユーザーが明示的に選ばない限りは type: "basic" （無料）を使います。まだ Space が存在しない場合は スペース を含めないでください — 後で追加できます。
Space をどう作るか決める。 2 つの道があります:
- サイト全体の Git Sync（推奨、デフォルト）: ユーザーに Git Sync をサイトのサイドバーから 1 回開き、リポジトリ/ブランチを接続し、各 Space を コンテンツのマッピング配下のディレクトリに割り当てるよう指示します。この 1 回の UI 操作で、すべての Space がサイトに作成/接続され、全体の sync も一気に設定されます。このスキルの役目は、その 1 回の操作について正確でコピペ可能な手順を与えることです。参照先: references/git-sync-handoff.md.
- プログラム先行: 空の Space を直接作成し、サイト Space としてサイトに追加し、content import か template 適用でコンテンツを読み込みます。双方向 sync を望むなら、後で UI で Git Sync を接続する必要があります。その際も、デフォルトで案内すべきは Space ごとではなくサイト全体です。
セクションを追加する （グループ化されたナビゲーションを持つ複数 Space サイト）: セクションは、Space にタイトルと任意のアイコンを結びつけることで作成されます。
Space 間リンクのシンボルを解決する: もしスキャフォールド済み Markdown に XSPACE_<KEY> プレースホルダーが含まれているなら（Space 境界をまたぐリンクには、そうあるべきです）、ここで step 3 または 4 が返した本物の Space ID に置換します。置換スクリプトは references/cross-space-links.md を参照してください。変更を commit して push します — 次の Git Sync 実行で取り込まれます。
カスタマイズ（ブランド設定）を適用する — 完全なスキーマは広範です: theme preset、色（それぞれ {light, dark} のテーマペア）、favicon、header（logo、primaryLink、links）、footer（links のグループ、copyright）、themes（default light/dark、切替可能）、AI mode、PDF 出力など。一般的なブランディングのレシピは references/customization-recipes.mdにあります。変更したいフィールドだけを変更してください — まず現在の設定を取得し、メモリ上で修正し、部分ペイロードを推測するのではなく完全な結果を書き戻します。
確認: サイトの structure を取得して最終ツリーを確認し、customization を取得して設定を確認します。

多言語サイトと自動翻訳 Space

GitBook は 自動翻訳された site-space: 1 つの英語 Space（Git で同期済み）を、他言語での計算済み翻訳と組み合わせられます。翻訳は Git リポジトリ内の別 Space ではありません — GitBook 内だけに存在し、各セクションの設定の UI から構成します。追加の site-space オブジェクトとして同じセクション内に現れ、それぞれ異なる 言語 を持ち、 gitSync フィールドを使います。

を持ちません。

実務上の意味は次のとおりです: リポジトリには、トピックごとに 1 つの Space が英語で存在します。このスキルは、コンテンツ領域ごとに 1 セットの Markdown ファイルを書くだけです。
各セクションは複数の site-space を持てます。 「Payments」セクションには、 Payments （en, git-synced）、 Payments (FR) （fr, computed）、 Payments (DE) （de, computed）などが含まれます。structure のレスポンスにはそれらすべてが列挙されますが、Git Sync の handoff が必要なのは英語版だけです。
localizedTitle があらゆる場所に現れます。 セクション、セクショングループ、ヘッダーリンク、フッターリンク、そしてサイトタイトルそのものにはすべて localizedTitle: {de: "...", fr: "...", ...} マップが付きます。customization を読むときは、ユーザーが英語でしか設定していないフィールドでも翻訳が見えるはずだと想定してください。求められない限り、これらを取り除かないでください。
自動翻訳は現時点では UI 専用機能です。セクションで有効化したいなら、サイト全体の Git Sync handoff の一部として次のように案内してください: 「Git Sync を設定したら、 Site → Sections → Payments → Translations へ行き、使いたい言語を有効化してください。」

ユーザーが「5 言語のドキュメントサイト」を求めたら、答えは Git で管理する英語のコンテンツツリー 1 つと、UI でセクションごとに有効化された自動翻訳です — Markdown のコピーを 5 個作ることではありません。

セクショングループ

サイトの構造には、ナビゲーション上 3 つの入れ子レベルがあります:

Site-spaces ルート直下で（フラットなサイト、セクションなし）
セクション サイトスペースを含む（典型的な複数スペースのサイト）
セクショングループ サイトスペースを含むセクションを含む（関連するセクションをまとめるために使用。たとえば、"Products" グループに Payments / Identity / Connect のセクションを含める）

サイトの構造レスポンスは再帰的です — セクショングループの セクション 配列には、セクションと他のセクショングループの両方を含められます。構造を設計する際は、トップナビで視覚的にまとめると有益な、密接に関連したセクションが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」と Scenarios 4–5 を参照してください。Premium および Ultimate の機能（カスタムロゴ、カスタムフォント、セマンティックカラー、フッターロゴ、高度なカスタマイズ）は無料サイトでは拒否されます。丁寧に処理してください。REST パスでは、 references/api-cheatsheet.md で正確なエラーレスポンスを確認してください。

references/customization-recipes.md には、以下の作業例があります。最小限のブランド適用（色 + favicon のみ）、ロゴとフォントを含む完全なブランド適用、トグル付きのダークモードのみ、提案プロンプト付きの AI アシスタント有効化。

学習用の完全な実例ペイロードとしては、 references/example-site/customization.json は、このスキルに付属する本番サイトのカスタマイズエクスポートです。実際にすべてのフィールドがどう組み合わさるかを最速で把握できるので、抽象的なスキーマよりずっと有用です。新しいサイトに丸ごと貼り付けないでください。形とフィールド選択のモデルとして使ってください。

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

Git Sync の引き継ぎ

これは洗練されていると感じられるべき部分です。リポジトリをプッシュしてサイトが存在するようになったら、スペースごとではなく、サイト全体に対して1つの明確な引き継ぎを作成してください。ユーザーが必要とするのは次の内容です：

リポジトリURLとブランチ名（通常は main)
サイトの プロジェクトディレクトリ — どこに gitbook-docs.yaml があるか（これは大きなモノレポでない限り、空/ルート）
初期同期の方向 — ほぼ常に GitHub → GitBook （または GitLab → GitBook）。この時点ではリポジトリが正本だからです
サーバー側の コンテンツマッピング — 各スペースのタイトルと、そのディレクトリの対応付け（例： ガイド → ./guides, API リファレンス → ./api-reference)

references/git-sync-handoff.md には、ユーザーに渡せるテンプレートがあります。1回接続し、同じパスで全スペースをマッピングしてください。文章をだらだら書くのではなく、1つの番号付きリストとして表示し、スペースごとに繰り返さないでください。特定のスペースを独立したリポジトリ/ブランチに切り出す必要がある場合にのみ、2つ目の引き継ぎブロックを追加してください。そのファイルの「When a space needs its own repo or branch」を参照してください。ユーザーが終えたら確認を求めてください。その時点で各スペースの同期状態をプログラム的に確認できます（まだサイトレベルのステータスエンドポイントはないので、内部的には依然としてスペースごとの確認です）。

よくあるミス

PAT を Claude が書くファイルに入れないでください。 必ず環境変数から読み取ってください。
コンテンツソースを黙って差し替えないでください。 ユーザーが指定したリポジトリやフォルダが読み取れない場合は（覚えておいてください：プライベートリポジトリは存在しないものと同じく 404 を返します）、止まって確認してください。見た目が似た公開リポジトリに進んではいけません。「Verify the content source before building.」を参照してください。
Git Sync をプログラム的に設定しようとしないでください。 これはトランスポートに関係なく UI のみです。必ず UI の引き継ぎ経由で進めてください。（installGitSyncProviderOnTarget は API に存在しますが、OAuth ステップを不要にはせず、まだ MCP 経由でも公開されていません — 近道に見えても引き継ぎを迂回しないでください。）
Git Sync を1スペースずつ引き継がないでください。 サイト全体の Git Sync が既定です — 1つの接続、全スペースに対する1回のコンテンツマッピング。個別のスペースに独立したリポジトリやブランチが必要な場合にのみ、スペースごとの Git Sync にフォールバックしてください。
カスタマイズペイロード全体を記憶だけで貼り付けないでください。 現在の状態を取得し、それを修正してから、完全な結果を書き戻してください。スキーマは進化するので、この方法の方がバグが少なくなります。
コンテンツの各セクションごとにスペースを作らないでください。 スペースは重い単位です（独自のURLスラッグ、同期、設定を持ちます）。スペース内のページやフォルダが、サブグループ化のための適切なツールです。
構造の計画と確認のステップを飛ばさないでください。たとえユーザーが急いでいてもです。公開済みサイトの再構成はつらいです。
SUMMARY.md を過度に整形しないでください。 GitBook のパーサーはこれに厳格です。 write-docs.
にあるルールに従ってください。変更リクエストの編集を両方のリンクなしで終えないでください。 「After a change-request push: two links are mandatory」を参照してください — CR の diff リンクだけでは不完全な回答です。

参考ファイル

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 自動生成、レイアウトフラグ、カードテーブル、条件付きコンテンツ、include、vars）付きで示したもの。 非自明なページを生成する前に、これを読んでください。
references/cross-space-links.md — markdown 内のスペース横断リンクのための sentinel-and-resolve ワークフロー。実用的な置換スクリプト付き
references/git-sync-handoff.md — ユーザー向けの Git Sync 設定手順テンプレート。サイト全体を先にし、文書化されたフォールバックとしてスペースごと設定を使う
references/customization-recipes.md — 一般的なシナリオ向けの作業済みブランディングペイロード
references/example-site/ — 実在の本番風 GitBook サイトリポジトリの、整理済みスナップショット（約150ファイル）。markdown、 SUMMARY.mds、 .gitbook/ configs）。 PRUNE-NOTES.md をまず読んでください。何を残し、何を削除したか、特定パターン向けの重要ファイル一覧が説明されています。
references/example-site/customization.json — そのサイトからのカスタマイズエクスポートで、完全な実世界のブランディングペイロードを示しています
references/example-site/structure.json — 構造エクスポートで、セクション、セクショングループ、多言語サイトスペース（英語は Git 同期 + 自動翻訳）を示しています

最終更新 16 日前

役に立ちましたか？