> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/ja-gitbook-documentation/skill/configure-site.md). # サイトを設定する GitBookドキュメントサイト全体をエンドツーエンドで作成・維持する — ソースコンテンツからサイト構造を設計し、モノレポ構成でGitリポジトリをスキャフォールド作成し、GitHub/GitLabのリモートを設定し、推進する GitBook のドキュメントサイト全体を作成・維持するためのスキル。これが `write-docs` 単一ページの中身を扱うのに対し、このスキルはページの周辺すべてを扱います: 構造設計、リポジトリのひな形作成、GitBook API、ブランディング。2つのスキルを一緒に使ってください — こちらは `write-docs` ページ内容の生成や編集が必要なときはいつでも呼び出します。 ## GitBook とやり取りする方法 GitBook を操作する方法は1つではありません — GitBook の MCP サーバーと REST API があります。現在のセッションで実際に利用可能なものを確認し、 **まず MCP**：GitBook の MCP ツールがすでに接続されているなら、カバー範囲内のこと（サイトの作成/設定、変更リクエストの作成、コンテンツの下書きと編集、ドキュメントの再構成）には、直接 API 呼び出しの代わりにそれらを使ってください。これのために検出スクリプトを実行しないでください — 自分が使えるツール/MCP 接続はすでに分かっているはずです。その認識をそのまま使ってください。 **「MCP first」は配信経路の話であって、コンテンツに Git Sync を回避する話ではありません。** MCP は変更リクエストのコンテンツ送信ツール（`updateChangeRequestContent`）を公開しており、接続されているならいつでも使いたくなります — しかし、すでに Git Sync が設定されているスペースでは、小さく限定的な編集以外は、ローカルのリポジトリ内でファイルを編集してコンテンツを押し出し、Git Sync に GitBook へ流してもらう方法が依然として推奨です。スペースが Git 同期されていない、環境内でローカルチェックアウトを利用できない、または編集が小さくて変更リクエストを開くのが妥当な場合には、代わりに変更リクエスト送信（MCP または REST）を使ってください。 `write-docs`の「Git Sync と変更リクエストのコンテンツ送信のどちらを選ぶか」を参照してください。完全なルールがあり、ここにも適用されます。 このスキルの手順は、1つの配信経路に結びついたものではなく、結果（「組織を一覧する」「サイトを作成する」「セクションを追加する」）として記述されています。そのため、どれを使っても適用できます。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 ヘッダーとして必要とします。 同じ個人アクセストークン（ で取得）は、どちらでも bearer トークンとして使えます。MCP はさらに、トークンを貼り付けるより使いやすい代替手段として OAuth もサポートします。 **トークンが必要になった場合** （REST API 経路、または OAuth なしの MCP）では、セッション開始時に次を確認してください: ```bash [ -n "$GITBOOK_TOKEN" ] && echo "Token found" || echo "GITBOOK_TOKEN is not set" ``` もし `GITBOOK_TOKEN` が設定されていない場合は、ユーザーに直接尋ねてください: 1. GitBook の個人アクセストークンが必要だと伝えてください。 **** で作成するよう案内してください。 2. 会話にトークンを貼り付けるよう依頼してください。すぐに環境変数としてエクスポートし（`export GITBOOK_TOKEN=`）応答でそれを繰り返し記載しないでください。 3. 環境内にトークンが存在することが確認されるまで、API 呼び出しは進めないでください。 トークンをファイルに書き込まないでください。応答で繰り返さないでください。コミットもしないでください。 ## 根本的な制約 何かを始める前に、まず最も重要な点を理解してください: **GitBook は、配信経路にかかわらず、Git Sync の設定以外はほとんど何でもできます**。GitHub/GitLab の認可、リポジトリの選択、ブランチの選択、初回の同期方向の選択はすべて UI だけの操作です — REST API も、それをラップする MCP も、できるのは *読み取る* 最終的な Git Sync 状態を読み取ることだけで、設定することはできません。API 操作として `installGitSyncProviderOnTarget`があります。これは site か space のどちらかを対象にしますが、アカウント接続（OAuth）のステップは依然としてアプリ内で行う必要があり、現時点では GitBook の MCP サーバー経由では公開されていません — まだ使えないものとして扱い、その上にフローを組まないでください。 **Git Sync は現在 site レベルで設定され、それがデフォルトで選ぶべきものです。** 1つの接続（1つの repo、1つの branch）でサイト全体をカバーします; `gitbook-docs.yaml` は各 space をそれぞれのディレクトリに対応付けます。これは、このスキルがすでにモノレポとしてひな形を作る形と同じです。space ごとの Git Sync もまだありますが、今では例外です — 特定の space に独立した repo や branch が必要な場合（例: 公開 docs repo に置けない private space）にだけ使ってください。 つまり、最もきれいなエンドツーエンドの流れは常に次のとおりです: 1. Claude は、ローカルに Git repo をモノレポとしてひな形作成し（space ごとに1ディレクトリ）、理想的には `gitbook-docs.yaml` 事前作成済みの、各 space をそのディレクトリに割り当てるマッピングを含め、ツールが許せばリモートへ push します 2. Claude は site、sections、そして作成可能な空の spaces を作成します 3. **ユーザーは GitBook で1回だけ、短く手順化された UI ステップを行います: site を repo/branch に接続し、space とディレクトリの対応付けを確認します** — space ごとではありません 4. Claude がブランディング/カスタマイズを適用します 手順 3 でのユーザーの役割は避けられませんが、驚きであってはなりません — そのため、明確でコピペ可能な指示を生成してください。参照: `references/git-sync-handoff.md`. ユーザーが Git Sync を明示的に望まない場合は、コンテンツインポート経路（content import と template application）にフォールバックしてください — これは下で簡単に説明し、 `references/api-cheatsheet.md`. ## 最初に集めるべき入力 これらが分かるまで、ひな形作成を始めないでください。何か足りないものがあれば、推測せずに焦点を絞った質問を1回してください。（認証は別に処理されます — 上の「GitBook とやり取りする方法」を参照。） * **組織** — ユーザーの組織一覧を取得し、 **一覧をユーザーに見せて、どれが対象か名前で確認してもらってください**。たとえ組織が1つしかなくても、最初に1回確認しておくのは、間違った場所に site を作ってしまうのを防ぐ安価な保険です。選んだ `organizationId` をセッション残りの間は使い続け、後続の手順を説明するときは組織を UUID ではなく title で呼んでください。 * **site の計画と可視性** — **デフォルトは `type: site` Ultimate プランの**、public visibility とし、ユーザーが明示的に別の指定をした場合のみ変えてください。実際の多くの利用者は Ultimate の機能セット（カスタムドメイン、AI Assistant、高度なカスタマイズ、GitBook の透かし非表示、カスタムフォント、カスタムロゴ）を求めています。無料枠（`type: basic`）は、個人のオープンソースのサイドプロジェクトのような、明らかに低リスクなユースケースにのみ適しています。迷ったら、こう聞いてください: *「特に無料枠をご希望でなければ、Ultimate プランで設定します — ダウングレードしましょうか？」* — `basic` basic では静かに欠けている Ultimate 機能（AI Assistant なし、カスタムフォントなし、カスタムドメインなし）は、プランを短く確認するよりはるかに大きな驚きになります。 * **コンテンツの元** — site は何から作るのか？よくある形: * 既存の markdown フォルダ — 最もきれいな出発点 * いくつかのメモと、参考としての競合サイト * 何をドキュメント化したいかの説明だけ * 再構成したい既存 site（その場合はまず site の現在の構造を取得する） * **A migration** 別の docs プラットフォームからの移行（Mintlify、Docusaurus、ReadTheDocs、GitBook v1）— 手順は `references/migration-from-other-platforms.md` を参照してください。移行はそれ自体が一つの技法です。単なるファイルコピーの格上げ版として扱わないでください。 * **API リファレンス用の OpenAPI 仕様** — site に API リファレンスの内容があるなら、 **OpenAPI 仕様があるかを事前に確認してください** （あるいはコードベースから生成できるか）。もしあるなら、API リファレンス space は `builtin:openapi` の SUMMARY エントリと、リソースごとの1段落の概要 README です — 手作業で endpoint ページを書くより圧倒的に手間が少なく、内容がずれません。参照: `references/block-ecosystem.md` と `references/api-cheatsheet.md` の手順を参照してください。 **手書きの endpoint ページをデフォルトにしないでください** — それはほとんどいつも誤った選択です。 * **ブランディング** — 最低でもプライマリカラー（hex）。任意で、ロゴ URL（ライト + ダーク）、favicon、フォントの選択（または GitBook のデフォルトのいずれか）、ヘッダーリンク、フッターテキスト/リンク、テーマプリセット（`クリーン`, `ミュート`, `ボールド`, `グラデーション`）。Ultimate site では、AI assistant 用の初期プロンプト（訪問者がよく尋ねそうな短い質問を3〜5個）も検討してください。 * **サイト構造** — site-spaces ではなく sections です。site に space が複数ある場合は、 **section 一覧** section 一覧をユーザーと明示的に詰めてください。各 section には title、Font Awesome のアイコン名、description があります。section のアイコンと description はナビゲーションの重要な要素で、訪問者にも見えます。最初に集めておけば、後から section ごとに追加入力する手間が省けます。例: `[{"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) ローカルでコミットして、ユーザーへの引き継ぎの最初に「リモートを作成して push する」手順を置く、または (2) ツールをインストールするようユーザーに依頼する。黙ってローカルのみをデフォルトにしないでください — リモートも手順もない repo になってしまいます。 * **site の形** — 単一 space か複数 space か。複数 space の site では **sections** を使ってナビゲーション内で space をまとめます。これは、内容の対象読者が明確に異なる場合（例: user docs + API reference + changelog）に適切な選択です。site-spaces を直接使うのは翻訳バージョンの場合だけです — 参照: `references/api-cheatsheet.md`. ## 構築前にコンテンツの出所を確認する ユーザーがコンテンツの元（repo、フォルダ、または docs サイト URL）を指定したら、構造を設計したり何かをひな形作成したりする前に、実際に読み取れることを確認してください: **前に** 構造を設計したり何かをひな形作成したりする前に: 1. **ソースを解決し、そのまま返してください。** これから何を読むのか（repo URL とブランチ、フォルダパス、または site URL）を正確に示し、上位階層の内容 — 短いファイル一覧またはページ一覧 — を見せて、ユーザーが正しいものか確認できるようにしてください。 2. **アクセスできない場合は、そこで止めてそう伝えてください。** Git ホストは **非公開リポジトリに対して 404 を返します** — 「リポジトリが存在しない」と区別できません。ユーザーが指定した repo での 404 や clone 失敗は、 *非公開の可能性あり*として扱ってください: 何が失敗したかをユーザーに伝え、コンテンツにアクセスできるようにする（ローカル clone、アーカイブ、認証済み `gh`/`glab`、public mirror）か、URL を修正するよう依頼してください。認証済みの `gh`/`glab` CLI が利用可能かを確認してから、repo に到達できないと判断してください。 3. **ソースを勝手に差し替えないでください。** 検索したり、推測したり、同名の類似 repo や site にフォールバックしたりしないでください — たとえ見た目が同じでも。誤ったソースから docs サイトを作るのは、確認のために止まるよりはるかに悪いです。ソースを変えるには、ユーザーの明示的な承認が必要です。 ## 状態変更操作の確認ゲート site の作成、space の作成、section の追加、site-space の接続、カスタマイズ変更はいずれも、組織内の全員に **すぐ見える** うえ、後片付けにもかなりの手間がかかるオブジェクトを作成または変更します。重い操作として扱ってください。 ルール: **何が起こるかを一画面で正確に示したプレビューをユーザーに先に見せ、明示的な「yes」を得るまでは、状態変更を行わないでください。** 良いプレビューは、短く具体的です: > 組織 **Acme Inc** (`org_abc123`): > > * サイトを作成 **「Acme Platform Docs」** （type: site, plan: ultimate, visibility: public） > * 空の space を3つ作成: **ガイド**, **API リファレンス**, **更新情報** > * Guides を既定の section として追加し、API Reference と Changelog 用の section を作成 > > 続行しますか？ (yes/no) 悪いプレビューは曖昧（「今から site を作ります」）か、長い説明の壁に埋もれています。見やすくしてください。 同じルールは破壊的操作にも当てはまります — site、space、section、またはカスタマイズ上書きの削除 — ただし、さらに曖昧さを減らしてください（「これは site を削除します **Acme Platform Docs** と、その3つの space も一緒です。space と site は7日間復元可能で、その後は永久削除されます。確認しますか？」）。 ユーザーが構造設計の段階で複数手順の計画をすでに確認しているなら、その計画内の個々の操作ごとに再確認する必要はありません — ただし、計画のどこかが変わったら（space が1つ増える、可視性が変わるなど）、再確認してください。 読み取り専用操作（取得や一覧表示）には確認は不要です。 ## 変更リクエスト送信後: 2つのリンクが必須 このスキル（または `write-docs`、ページ作成を委譲している相手も含む）が、変更リクエスト経由でコンテンツを送るとき — MCP の `updateChangeRequestContent`/`create_change_request`/`submit_or_merge_change_request` curated tools, `invoke_operation`、または REST の同等手段を通じて — 編集は **まだ完了していません** 次の2つの内容が毎回ユーザーに報告されるまで完了しません: 1. **変更リクエストの diff/editor リンク** (`urls.app`）— GitBook アプリで変更を確認するためのリンクです。 2. **サイトのプレビューリンク** — 変更が適用されたレンダリング済み docs です。これは別途取得が必要です: site URL は **Site** オブジェクト（`urls.published` サイトが公開されている場合は、そうでなければ `urls.preview`）にあり、変更リクエストオブジェクトにはありません。また **それに `/~/changes//` を付け足し**、API が返す末尾のスラッシュを取り除いてください。その部分がないと、そのリンクは site の *現在の* 内容を表示してしまい、この変更リクエストではありません — ちゃんと読み込めてしまうのに、間違ったものが表示されます。 これは厳格なルールで、上の確認ゲートと同等です — 時間があれば付け足す程度のものではありません。参照: `write-docs`の「変更リクエストが関わるときは常に2つのリンクが必須」と `cr-create` スキルの「プレビューリンクの表示」で、正確な解決手順を確認してください（MCP: `getSpaceById` → site を見つけるには `list_sites`/`get_site_structure` または各 site の site-spaces → `getSiteById` で `.urls.preview`；REST: それに相当する連鎖 `GET` 呼び出し）。space が公開済み site に接続されていない場合は、説明なしで diff リンクだけを示すのではなく、その旨をはっきり伝えてください。 ## site 構造の設計 ファイルを書いたり GitBook で何かを作成したりする前に、構造を決めてユーザーに確認してください。構造が弱いことは、docs site が受け入れられない最大の原因です。 この手順の出力は小さな計画で、理想的には次の3要素です: 1. **space 一覧** — 一貫した内容のまとまりごとに1 space。小さく保ってください（1〜4 spaces が一般的です）。space はナビゲーションと Git Sync の単位なので、1つの対象読者の内容を複数の space に分けないでください。 2. **section のグルーピング** （複数 space の場合）— sections は site ナビゲーションの最上位区分です。例: 「Product」/「Developers」/「Resources」。section には1つ以上の space を入れられます。 3. **space ごとのページツリー** — フォルダとページ、および各ページの1〜2文の要約。深さは内容に合わせてください。浅いツリー（1〜2階層）が通常は最適です。 生の入力から構造計画へ進めるためのヒューリスティック一式は `references/site-structure-design.md` — 非自明な site でこれを初めて行うときは読んでください。 **ひな形作成の前に、必ず計画をユーザーに見せて明示的な承認を得てください。** 後で再構成するのは Git の中では安価ですが、site が公開されインデックスされると高くつきます。 ユーザーが1つにまとめた指示を与えたときの確認についての注意: *「構造を計画してからそれをひな形作成する」* は、ゲートを飛ばしたくなる誘惑があります。だめです。計画を明確で読みやすいブロックとして提示し、その後は「yes」を待つか — もしプロンプトがそれほど明示的で、すでにひな形作成を始めてしまっているなら — 計画で決めた内容を見せ、軌道修正できる簡単な機会を1回だけ与えてください（「もし違っていたら言ってください。先に進む前にやり直します」）。大事なのは、ユーザーが計画を見た状態で **前に** 20個の生成ファイルを前にする前に、やり直しがまだ安い段階であることです。 ## リポジトリのひな形作成 構造が合意できたら、repo はモノレポとして配置してください — 単一 space の site でも、これが一貫していて将来にも強いです。各 space はそれぞれの `README.md` （homepage）と `SUMMARY.md` （目次）を含むディレクトリです。必要に応じて、space ごとの変数や再利用可能なコンテンツブロック用の `.gitbook/` フォルダ、さらに高度な同期設定用の `.gitbook.yaml` を含めます。 3 space の site のレイアウト例: ``` 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` space ごとに `.gitbook.yaml` ルートを上書きする、リダイレクトを定義する、または他の非デフォルトのことをするときだけ、`references/example-site/`）には0個の `.gitbook.yaml` ファイルしかありませんが、完全に問題なく動作します。 * **`.gitbook/vars.yaml`** には、ページがインラインで参照できる space スコープの変数が入ります（例: `support_email: support@evolve.com` として参照: `{% vars.support_email %}`）。多くのページに出る値に便利です。 * **`.gitbook/includes/.md`** には、再利用可能なコンテンツブロックが入ります — 多くのページに `{% include "...persona-switcher" %}`で埋め込むスニペットです。定型文をコピペする代わりにこれらを使ってください。 * space のディレクトリ名（例: `guides/`）が、ユーザーがその space を **コンテンツのマッピング** で site 全体の Git Sync を接続するときに割り当てる対象です — site の「Project directory」フィールドではありません。そちらは `gitbook-docs.yaml` 自体がどこにあるか（このレイアウトでは repo ルート）を指すだけです。2つを混同しないでください。参照: `references/git-sync-handoff.md`. * 事前に `gitbook-docs.yaml` を repo ルートに用意し、各 space をそれぞれのディレクトリに対応付けることを検討してください（形は `references/git-sync-handoff.md` を参照）。GitBook は初回同期時にそれを読み込むので、セットアップ時にユーザーが手で入力する量が減ります。 最小限の `.gitbook.yaml`が必要な場合の例は次のとおりです: ```yaml root: ./ structure: readme: README.md summary: SUMMARY.md ``` ### repo レベルの README と .gitignore repo レベルの `README.md` （repo の先頭、space 内ではない）は、そのフォルダが何で、公開済み site とどう関係するかを説明すべきです — docs そのものを重複させないでください。短い段落で十分です: ```markdown # my-docs [My Product docs site](https://docs.example.com) のソースです。各トップレベルフォルダ はそれぞれ別の GitBook space です。設定後は Git Sync により編集が双方向に流れます。 ``` 1つの `.gitignore` は OS のゴミファイルやエディタ設定を repo から除外すべきです。妥当なデフォルト: ``` .DS_Store Thumbs.db *.swp *.swo .idea/ .vscode/ ``` チームに他の生成物（例: 別の場所のソースから生成された OpenAPI 仕様）があるなら、それも追加してください。 ### SUMMARY.md の生成 — フォルダから推測せず、ナビゲーションを集める ひな形作成で最もよくある失敗は、ファイルツリーをなめてそのまま SUMMARY.md を出力してしまうことです: 先頭に README を置き、他のすべてのファイルを README の子としてインデントする。これでは気の抜けるナビゲーションになります — すべてのページが「ホームページの子」になり、フォルダ名は読者に意味があるかどうかに関係なくグループタイトルになり、情報アーキテクチャがユーザーの頭の中ではなくファイルシステムを映してしまいます。 **正しいパターンは、順番に次のとおりです:** 1. **構造設計の段階で、望むナビゲーションをユーザーから集めてください。** トップレベルページと各 space の名前付きグループを、明示的に列挙してもらってください。ここでフォルダ名をナビの現実に合わせ、ユーザーが「実は Authentication は Concepts の下ではなくトップレベルページにしたい」と言えるようにします。 2. **合意したナビに合わせてフォルダを配置し、逆にしないでください。** ユーザーが space 内に3つのグループ — 「Getting started」「Concepts」「Tutorials」— を望むなら、space ディレクトリにはその名前（slug 化済み）の3つのサブフォルダがあり、それぞれに自分のページが入ります。紛れ込んだサブフォルダから4つ目のグループを自動抽出しないでください。 3. **ユーザーが合意した明示的な形に合わせて SUMMARY.md を書いてください。** GitBook が受け入れる構文: ```markdown # 目次 * [Space homepage](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ページにつき1つの箇条書きで、余計な書式は付けません。** SUMMARY では太字も説明文も不要です — それらはページの frontmatter に置きます。 4. **特別扱いするパターン** で、通常の箇条書きではないもの: * **OpenAPI で自動生成されるエンドポイントページ** は、箇条書きの内容としてフェンス付き YAML ブロックを使います（`type: builtin:openapi` — 参照 `references/api-cheatsheet.md`). * **外部リンク** は `* [タイトル](https://...)` で、ナビゲーションでは外部リンクとして表示されます。 * **クロススペースリンク** は SUMMARY.md でも同じ `https://app.gitbook.com/s//` 形式を使います。パスには `.md` のサフィックスは付きません。スキャフォールディング中はセントネル形式（`XSPACE_`）を書き、スペース作成後に解決します。参照: `references/cross-space-links.md`. スキャフォールディング支援ツールがフォルダを走査して SUMMARY.md を自動生成するなら、 **それを冪等にし、すでに存在するファイルはスキップしてください**。ユーザーが編集した SUMMARY.md を黙って上書きしてはいけません — 手作業で調整したナビゲーションが失われる原因になります。 ### ページごとの Markdown — write-docs に従うが、リッチブロックは積極的に使う **すべての Markdown ファイルについて** — `README.md`, `SUMMARY.md`、各ページは — `write-docs` skill に従ってください。これは以下に関する権威ある参照です: * **フロントマター** を含む `icon:` フィールド。アイコンは、 `fa-` プレフィックスを除いた Font Awesome の名前です（例: `book-open`, `bolt`, `house`, `code`, `puzzle-piece`, `id-card`, `circle-dollar-to-slot`）。名前をでっち上げないでください — Font Awesome カタログから選んでください。サンプルサイトでは、ほぼすべてのページの frontmatter にこれらが使われています。 * **レイアウトフラグ** を含む `layout: width: wide` （選択的に使ってください — マーケティング風のランディングページ、Updates タイムラインのある changelog ページ、複数カラムのブロックや本当に幅広い表があるページなどで。 **すべてのスペースのホームページで wide をデフォルトにしないでください** — GitBook のデフォルト幅はドキュメントに適しており、カード表を使ったドキュメントのランディングページにも合っています。wide はヒーロー型のマーケティングレイアウト向けで、通常のドキュメント向けではありません。) `cover:` 画像、そしてページごとの表示フラグ（`title.visible`, `tableOfContents.visible`など）。 * **`SUMMARY.md` 文法。** 厳格な形式 — 1ページにつき1つの箇条書き、必要に応じて `## グループ名` 見出し、余計な書式なし。さらに、仕様からエンドポイントページを自動生成するための特別な `type: builtin:openapi` 構文もあります。 * **リッチブロック** — タブ、ヒント、ステッパー、カラム、カード表、展開ブロック、埋め込み、 `{% if visitor.claims... %}`を使った条件付きコンテンツ、OpenAPI ブロック、 **更新** ブロック（changelog）、再利用可能なコンテンツ includes。 * **GitBook 風 Markdown の CommonMark との違い** を。 ここでそれらを作り直さないでください。付属の `references/example-site/` は、慣用的なコンテンツがどう見えるかを示す実用上最良の参照です。 ### 適切なブロックを選ぶ — デフォルトではなく、積極的に よくある失敗: Claude が *動作する* ドキュメントを生成するものの、すべてを平文 Markdown で済ませてしまい、GitBook サイトを本物のプロダクトのように見せるリッチブロックを取り逃がすことです。 **skill は特化ブロックを積極的に使うべきで、**むき出しの文章と箇条書きに逃げないでください。内面化すべき具体的なパターン: * **Changelog** → `{% updates %}` ブロックと `{% update date="..." tags="..." %}` エントリ。RSS を自動生成し、タグをサポートします（ `.gitbook/tags.yaml`で定義）。 `## YYYY-MM-DD` の見出しは書かないでください — その形は間違いです。 * **API エンドポイント参照** → OpenAPI 仕様を1回アップロードし、 `type: builtin:openapi` を通じてページを自動生成します。SUMMARY.md での手作業によるエンドポイントページ作成はやめてください — ずれが生じますし、どうせ仕様が正です。ユーザーに仕様がないなら、文章ベースにするより最小限の仕様を下書きすることを提案してください。 * **状態機械、フロー、シーケンス、単純なアーキテクチャ** → ` ```mermaid ` のフェンス付きブロック。ASCII で箱と矢印を描かないでください。Mermaid はサポートされており、きれいに描画され、スクリーンリーダーにも優しいです。 * **スペースのホームページ** → 通常のドキュメントのランディングでは GitBook のデフォルトレイアウトを使ってください（TOC 表示、デフォルト幅）。 `layout: width: wide` を使うのは、ページが本当にマーケティング風の場合だけです — ヒーロー画像、異常に大きいカードグリッド、多段カラムのダッシュボードレイアウトなど。デフォルトはドキュメントに適しています。 * **「行き先を選ぶ」コンテンツ** → カード表（``）。HTML は冗長ですが、見た目の結果はどんな Markdown の代替よりも優れています。 * **左右並列の導入パターン** → `{% columns %}` ブロック。50/50 の2カラムが標準です。 * **繰り返し使う定型文（3か所以上）** → `.gitbook/includes/.md` + `{% include "..." %}`. * **繰り返し使うリテラル（環境URL、サポートメール、バージョン固定）** → `.gitbook/vars.yaml` + `space.vars.`. * **複数言語のコードサンプル** → `{% tabs %}` ブロック。 * **3ステップ以上の順序付き手順のウォークスルー** → `{% stepper %}` ブロック。 例の呼び出しと smell-vs-fix の判断表を含む完全なブロック別ガイドは、 `references/block-ecosystem.md`. **にあります。**トリビアルでないページを生成する前に読み、スキャフォールディングする各コンテンツ領域について判断表をたどってください — 平文 Markdown に逃げる前に「これに特化したブロックはあるか?」と問いかけてください。 ### クロススペースリンク 複数スペースのサイト *は* クロススペースリンクを必要とします — それが、サイトをばらばらのマニュアルの集まりではなく、1つにつながったプロダクトのように感じさせる方法です。 **それを避けるためにコンテンツを複製したり、逆に捨てたりしないでください。** それらは GitBook の第一級機能です。ただし、正しく描画するには本物の space ID が必要で、その ID はサイト作成後にしか存在しません。 Markdown でのパターンは、対象スペースの GitBook URL への通常のリンクです: ```markdown 概念面については、[認証の概念ページ](https://app.gitbook.com/s//concepts/authentication) を参照してください。 ``` GitBook は `https://app.gitbook.com/s//` を、カスタムドメインに関係なくレンダリング時に解決します。内部的にはこれらは `ContentRefPage` または `ContentRefSpace` スペース ID が設定されたコンテンツ参照であり、Markdown では単に URL として見えます。 **スキャフォールディングの流れ:** 1. **スキャフォールディング中は**、計画中の各スペースにつき1つ、プレースホルダーの space-ID に `XSPACE_`をプレフィックスとして付けたクロススペースリンクを書きます。構造計画の space スラッグをサフィックスとして使ってください: ```markdown [認証の概念ページ](https://app.gitbook.com/s/XSPACE_GUIDES/concepts/authentication) を参照してください。 完全な参照は、[API Reference](https://app.gitbook.com/s/XSPACE_API/) を参照してください。 ``` これらは存在しない GitBook スペースへの有効な Markdown リンクです — パーサーを壊さず、grep しやすく、Git を通してもきれいに往復できます。 2. **スペース作成後**は、各新スペースの本物の ID を手に入れたら、すべての Markdown ファイルを走査して `XSPACE_` を本物の space ID に置き換えます: ```bash 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 経由でそれを取り込み、リンクは次回レンダリング時に解決されます。 きれいに実装するなら、 `cross-space-links.yaml` をリポジトリのルートに置き、セントネルキーから space ID への対応をマッピングし、作成後に生成してください。そうしておけば、誰かが再実行しても解決スクリプトを再現できます。アンカーリンク、ページ固有リンク、サンプルの解決スクリプトを含む完全なパターンは、 `references/cross-space-links.md`. **これはどこに書き込まれるか:** スキャフォールド（セントネル付き）、スペース間で生成する Markdown コンテンツ、そして作成後の解決ステップです。実際の `app.gitbook.com/s//...` リンクをスキャフォールディング中に書こうとしないでください — ID はまだ存在せず、推測しても壊れたリンクになります。 ### サンプルコンテンツの探し方 `references/example-site/` は **切り詰めたスナップショット** で、この skill に同梱された本番風 GitBook サイトのものです。元のサイトは12スペース構成（ホーム、3つのプロダクトスペース、開発者 API の3バージョン、3つのガイドスペース、パートナー、changelog、さらに外部コンテンツの `connections/` tree）で、約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 も元のツリーを記述しており、一部のリンクは削除済みページを指していますが、それは想定どおりです。 注目すべきファイル **、示したいパターンごとに整理すると**: | パターン | 読むファイル | | ------------------------------------------ | ------------------------------------------------------------------------------------------------ | | Updates ブロック + タグ | `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` | | 条件付きコンテンツ via `{% 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` | | 再利用可能なコンテンツ includes | `home/.gitbook/includes/persona-switcher.md` | | `.gitbook/vars.yaml` variables | 任意のスペースの `.gitbook/vars.yaml` | | グループ化された SUMMARY.md（セクションは `## 見出し`) | 任意のスペースごとの `SUMMARY.md` ファイル | 同梱スナップショットに含まれていないパターンが必要な場合（例: 旧/ベータ版の API スペースを並べて置く、外部コンテンツ記事カタログ全体など）、 `structure.json` は形の正しい唯一の情報源であり、PRUNE-NOTES.md はそれらの省略が表していたパターンを説明しています。 スキャフォールディング後: ```bash cd my-docs git init git add . git commit -m "Initial scaffold" ``` ユーザーがリモートを望み、 `gh`/`glab` が使えるなら: ```bash # GitHub gh repo create --private --source=. --push # GitLab glab repo create --private && git push -u origin main ``` どちらのツールも使えないなら、 **それを明示的に伝え** スキャフォールディングが終わる前に。2つの有効な道があります: * **ローカル専用リポジトリ + 引き渡し時に手動でリモート設定。** ローカルでコミットし、引き渡しに「Step 0」を残して、次のように書いてください: *「あなたのマシンで、 ``という名前のプライベートな GitHub または GitLab リポジトリを作成し、 `git remote add origin && git push -u origin main` をこのディレクトリから実行してください。」* これは GitBook UI の手順より上に置いてください — Git Sync が接続する前に、リポジトリが push 済みである必要があります。 * **ユーザーに `gh` または `glab`.** のインストールを勧めてください 今後さらにサイトを作るなら、そのツールは持っていて損はありません。 ## 移行とコンテンツ品質 実際の構築の多くは新規作成ではありません — 別のドキュメントプラットフォーム（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 流儀で手作業作成するわけではありません。正しいやり方は、末端の長い部分を一括変換し、そのあとでホームページ、各スペースのトップレベルランディング、目玉のハウツーの4〜6ページを意図的に再構築し、フルのブロック群を使うことです。残りは段階的に標準へ引き上げれば十分です。 **フォーマット調整は、文書化された手順です。** 素朴な Markdown 変換では、異物のコンポーネントタグ、壊れたコードフェンス、壊れた内部リンクなどの残骸が残ります。一括変換後、最初のコミット前にクリーンアップを実行してください — サポートされないコンポーネントを削除し、フェンスを正規化し、 `/docs/...` のパスを GitBook の URL か相対パスに書き換えます。これをページごとにその場でやるとリンクが不揃いになります。slug-to-path の manifest を使って一括でやる方がずっと確実です。 *ほとんど* レンダリングされます。 **自動生成する frontmatter は、持っていないなら作らないでください。** 元にアイコンがなかったなら、URL スラッグからアイコンを自動選択しないでください — 不一致の cog アイコンだらけになります。元に説明文がなかったなら、その欄は空のままにしてください。 `Source: ` で埋めないでください（その文言はサイドバーのプレビューや検索に漏れます）。 **API 参照は OpenAPI-first で。** 移行先サイトに API リファレンスがあり、OpenAPI 仕様を入手できる（またはコードベースから生成できる）なら、参照スペース全体を `builtin:openapi`へ通してください。70ページの手変換リファレンスより、3ファイルの自動生成版の方がほとんど常に優れています。 **内部リンク変換はページ単位ではなく、全体一括で。** 構造が分かったら、すべての Markdown ファイルを走査して `/docs/...` リンクを、相対 `.md` パス（スペース内）か `https://app.gitbook.com/s//` URL（スペース間）に書き換えてください。ページごとに順次やるとリンクが不整合になります。slug-to-path の manifest を使って1回でやる方がはるかに信頼できます。 **コンテンツを再生成するヘルパースクリプトには注意してください。** コンバータや SUMMARY ジェネレータを使うなら、デフォルトで冪等にしてください。すでに存在するファイルはスキップしてください。手作業で調整したホームページを2回目の実行で潰すのは危険です。 `rm -rf /` を、手編集コンテンツを含む可能性のあるディレクトリで実行してはいけません。どうしても再生成が必要なら、 `/_generated/` に書き出してからマージまたは差分確認してください。 ## GitBook にサイトを構築させる 以下の手順はエンドポイント呼び出しではなく成果として説明しています — 上で「GitBook とどう会話するか」で選んだ手段を使ってください。REST API 経路では、各ステップの正確なエンドポイント、リクエストボディ、期待レスポンスは `references/api-cheatsheet.md`にあります。呼び出す前に読んでください — スキーマは微妙です（特に customization）。MCP 経路では、対応するツールが同じ手順をカバーします — REST のパスを調べるより、各ツール自身のスキーマを読んでください。 ### 新しいサイトの標準的な流れ 1. **アクセスを確認して org を見つける**: 認証済みユーザーを確認し、そのあと org を一覧表示します。 2. **サイトを作成する** で `{title, type, visibility, spaces?}`. **Ultimate をデフォルトにする** (`type: "site"`にしてください。プラン階層は作成後にサイト上、または org の請求設定で設定されます。） `type: "basic"` （無料）は、ユーザーが明示的に選んだ場合のみ使ってください。 `spaces` がまだ存在しないなら含めないでください — 後で追加できます。 3. **スペースをどう作るか決める。** 2つの道: * **サイト全体の Git Sync（推奨、デフォルト）**: ユーザーに開くよう伝えてください **Git Sync** サイトのサイドバーから一度だけ、リポジトリ/ブランチを接続し、各スペースをその下のディレクトリに対応付けます **コンテンツのマッピング**。この1回のUI操作で、すべてのスペースがサイトに作成/リンクされ、同期も一括で設定されます。このスキルの役目は、その1回の操作のための正確でコピペ可能な手順を示すことです。参照: `references/git-sync-handoff.md`. * **プログラム優先**：空のスペースを直接作成し、サイトスペースとしてサイトに追加してから、コンテンツのインポートまたはテンプレート適用で内容を読み込みます。双方向同期を望む場合、ユーザーは後でUIでGit Syncを設定する必要があります。その場合でも、まず案内すべき既定はサイト全体であり、1スペースずつではありません。 4. **セクションを追加** （ナビゲーションがグループ化されたマルチスペースサイト）：セクションは、スペースにタイトルと任意のアイコンを関連付けて作成されます。 5. **スペースをまたぐリンクのセントネルを解決**：生成されたMarkdownに `XSPACE_` のプレースホルダー（スペース境界をまたぐリンクでは必ずそうなるはずです）が含まれている場合、ここでステップ3または4で返された実際のスペースIDに置き換えます。参照: `references/cross-space-links.md` 置換スクリプトについて。変更をコミットしてプッシュしてください。次回の Git Sync 実行でそれらが取り込まれます。 6. **カスタマイズを適用** （ブランディング）— 完全なスキーマは広範で、テーマプリセット、カラー（それぞれ `{light, dark}` のペア）、favicon、ヘッダー（logo、primaryLink、links）、フッター（リンクのグループ、著作権）、テーマ（light/darkのデフォルト、切り替え可能）、AIモード、PDFエクスポートなどです。一般的なブランディングシナリオのレシピは `references/customization-recipes.md`にあります。変更したいフィールドだけを変更してください。まず現在の設定を取得し、メモリ上で修正してから、部分的なペイロードを推測するのではなく、完全な結果を書き戻します。 7. **検証**：サイトの構造を取得して最終的なツリーを確認し、カスタマイズを取得して設定を確認します。 ### 多言語サイトと自動翻訳されたスペース GitBook はサポートしています **自動翻訳されたサイトスペース**：Git から同期された1つの英語スペースに、他言語の生成済み翻訳を組み合わせることができます。翻訳は Git リポジトリ内の別スペースではなく、完全に GitBook 内に存在し、各セクションの設定からUIで構成します。これらは追加の `サイトスペース` オブジェクトとして同じセクション配下に表示され、それぞれ異なる `言語` であり、 `gitSync` フィールドはありません。 実際には次の意味です： * **リポジトリ内に言語ごとのディレクトリを生成しないでください。** 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 の設定後、 **サイト → セクション → Payments → 翻訳** に移動し、必要な言語を有効にしてください。」 ユーザーが「5言語のドキュメントサイト」を求める場合、答えは Git 上の英語のコンテンツツリー1つと、UIでセクションごとに有効化された自動翻訳です。Markdownを5部複製するわけではありません。 ### セクショングループ サイトの構造には、ナビゲーション上で3つのネスト階層があります： 1. **サイトスペース** ルート直下（フラットなサイト、セクションなし） 2. **セクション** サイトスペースを含む（典型的なマルチスペースサイト） 3. **セクショングループ** サイトスペースを含むセクションを含む（関連するセクションをまとめるために使用。たとえば「Products」グループに Payments / Identity / Connect の各セクションを含める場合など） サイトの構造レスポンスは再帰的です。セクショングループの `sections` 配列には、セクションと他のセクショングループの両方を含められます。構造を設計するときは、トップナビで視覚的にグループ化する価値がある、密接に関連するセクションが3つ以上ある場合にのみセクショングループを使ってください。2セクションのサイトなら、ルートレベルにセクションを置くほうが明確です。 ### 既存サイトの更新 すでに存在するサイトの変更を求められたら、 *必ず* まず現在の状態を取得してください： * サイトのメタデータ * 構造（セクション + スペース） * カスタマイズ（サイトレベルまたはサイトスペースごと）、ブランディング用 その後、全面置換ではなく対象を絞って変更します。1フィールドだけ変更したい場合にカスタマイズのペイロード全体を置き換えないでください。現在の設定を取得し、メモリ上で修正してから、完全な結果を書き戻します。 ### コンテンツインポートと Git Sync の使い分け * **コンテンツインポート** は、外部コンテンツ（Webサイト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` には、次の実例があります：最小限のブランド設定（色 + faviconのみ）、ロゴとフォントを含む完全なブランド設定、切り替え付きのダークモードのみ、提案プロンプト付きの AI アシスタント有効化。 学習用の完全な実運用ペイロードとしては、 `references/example-site/customization.json` は、このスキルに同梱されている本番サイトのカスタマイズエクスポートです。実際に各フィールドがどのように組み合わさるかを知る最短ルートであり、抽象的なスキーマよりずっと役立ちます。新しいサイトに丸ごと貼り付けず、形やフィールド選択の見本として使ってください。 構造レスポンス（セクション、セクショングループ、多言語サイトスペース）の実例については、 `references/example-site/structure.json` もあわせて参照してください。 ## Git Sync の引き継ぎ ここは洗練されて見える必要がある部分です。リポジトリがプッシュされ、サイトが存在したら、スペースごとではなく、サイト全体についての明確な引き継ぎを1つ生成してください。ユーザーに必要なのは： 1. リポジトリURLとブランチ名（通常は `main`) 2. サイトの **Project ディレクトリ** — どこに `gitbook-docs.yaml` が置かれているか（大きなモノレポでない限り、空白/ルート） 3. 初回同期の方向 — ほぼ常に **GitHub → GitBook** （または GitLab → GitBook）。この時点ではリポジトリが正本だからです 4. この **コンテンツのマッピング** — 各スペースのタイトルと対応するディレクトリ（例： `ガイド` → `./guides`, `API リファレンス` → `./api-reference`) `references/git-sync-handoff.md` には、埋めてユーザーに提示できるテンプレートがあります：1回接続し、同じ操作で全スペースをマッピングします。段落の羅列ではなく、スペースごとに繰り返すこともなく、1つの番号付きリストとして表示してください。特定のスペースを独立したリポジトリ/ブランチに切り出す必要がある場合にのみ、2つ目の引き継ぎブロックを追加します。その場合はこのファイルの「スペースに独自のリポジトリまたはブランチが必要な場合」を参照してください。ユーザーが完了したら確認を求めてください。その時点で、各スペースの同期状態をプログラム的に確認できます（現時点ではサイトレベルのステータスエンドポイントがないため、内部的には依然としてスペース単位のチェックです）。 ## 避けるべきよくあるミス * **Claude が書くどのファイルにも PAT を入れないでください。** 必ず環境変数から読み取ってください。 * **コンテンツソースを黙って差し替えないでください。** ユーザーが指定したリポジトリやフォルダが読み取れない場合（注意：プライベートリポジトリは存在しないものと同じく404を返します）、そこで止めて確認してください。そっくりな公開リポジトリで進めないでください。「ビルド前にコンテンツソースを検証する」を参照してください。 * **Git Sync をプログラムで設定しようとしないでください。** 輸送手段に関係なくUI専用です。必ずUIの引き継ぎを通してください。（`installGitSyncProviderOnTarget` はAPIには存在しますが、OAuthステップはなくならず、まだMCP経由では公開されていません。魅力的に見えても引き継ぎを迂回しないでください。） * **Git Sync をスペースごとに引き継がないでください。** サイト全体の Git Sync が既定です。接続は1回、コンテンツマッピングも全スペースで1回です。特定のスペースが独立したリポジトリまたはブランチを必要とする場合にのみ、スペースごとの Git Sync にフォールバックしてください。 * **カスタマイズのペイロード全体を記憶だけで貼り付けないでください。** 現在の状態を取得し、修正してから、完全な結果を書き戻してください。スキーマは進化するため、このやり方のほうがバグが少なくなります。 * **コンテンツの各セクションごとにスペースを作らないでください。** スペースは重い単位です（独自のURLスラッグ、同期、設定があります）。スペース内のページやフォルダこそが、サブグループ化に適した手段です。 * **構造を計画して確認する手順を飛ばさないでください**。ユーザーが急いでいても同様です。公開済みサイトの再構成はつらいものです。 * **SUMMARY.md を過度に整形しないでください。** GitBook のパーサーはこれに厳格です。次のルールに従ってください： `write-docs`. * **変更リクエストの編集は、両方のリンクが揃うまで完了させないでください。** 「変更リクエストをプッシュした後：2つのリンクが必須」を参照してください。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 ブロックを使うべきかを、判断表と実例（更新、Mermaid、OpenAPI自動生成、レイアウトフラグ、カードテーブル、条件付きコンテンツ、includes、vars）付きで示したもの。 **非自明なページを生成する前に、これを読んでください。** * `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`s、 `.gitbook/` 設定ファイル）。まず `PRUNE-NOTES.md` を読んでください。何が残され、何が削除されたかを説明し、特定のパターンに対して有用性の高いファイルを列挙しています。 * `references/example-site/customization.json` — そのサイトからのカスタマイズエクスポートで、実運用の完全なブランディングペイロードを示しています * `references/example-site/structure.json` — 構造エクスポートで、セクション、セクショングループ、多言語サイトスペース（英語は Git 同期 + 自動翻訳）を示しています --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/skill/configure-site.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.