write-docs

このスキルを使用する場面

次の方法で GitBook のドキュメントを扱うときに、このスキルを使用してください。

• Git と同期されたリポジトリ（GitHub、GitLab）
• ローカルの Markdown エディター
• IDE の統合機能
• GitBook の UI ではなく、ファイルとして GitBook のコンテンツを編集するあらゆる環境

クイックリファレンス

GitBook のコンテンツ構造

GitBook では、ページ、スペース、コレクションを使ってコンテンツを整理します。

• ページは、ドキュメントを構成する個々の Markdown ファイルです
• スペースは、ドキュメントサイトとして整理されたページの集合です
• コレクションは、スペースのグループです

ファイル構造：

/
  .gitbook/
    assets/              # GitBook-managed images and files
    includes/            # Reusable content blocks
    vars.yaml            # Space-level variables
  .gitbook.yaml          # Configuration
  README.md              # Homepage
  SUMMARY.md             # Table of contents
  getting-started/
    installation.md
    quickstart.md
  api-reference/
    authentication.md
    endpoints.md

フロントマターのフィールド（簡易形式）：

---
description: "Page description for SEO"
icon: book-open
hidden: true
vars:
  page_variable: value
layout:
  width: default  # or 'wide'
  tableOfContents:
    visible: true
  pagination:
    visible: true
---

変数と式：

• スペース変数：/.gitbook/vars.yaml
• ページ変数：フロントマターの vars:
• 式の構文：<code class="expression">space.vars.variableName</code>

よく使われるカスタムブロック：

• {% tabs %}...{% endtabs %} — 選択肢を提示します
• {% hint style="..." %}...{% endhint %} — コールアウト（情報／警告／危険／成功）
• {% stepper %}...{% endstepper %} — 順序に沿った手順
• <details>...<summary>...</details> — 展開可能なコンテンツ

リンク：

• 外部リンク：[text](https://example.com)
• 相対リンク（同じスペース）：[text](page.md)、[text](../folder/page.md)
• スペースをまたぐリンク（別のスペース）：[text](https://app.gitbook.com/s/<spaceId>/<path>) — 相対パスでスペースの境界を越えることはできません。また、/spaces/<id>/pages/<id> は有効なリンク形式ではありません。組織を指定したエイリアス https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path> も同じように解決されます。短い形式を記述してください。ただし、どちらの形式も書き換えたり、リンターの対象にしたりしないでください（references/git-sync-serialisation.md）。GET /orgs/{orgId}/spaces から <spaceId> を取得し、GET /spaces/{spaceId}/content/pages におけるページの path フィールドから <path> を取得してください。対象のスペースがまだ存在しないサイトを新しく作成する場合は、XSPACE_<KEY> センチネルを使用してください。configure-site がスペース作成後にそれらを解決します。完全な例については、references/markdown.md を参照してください。
• 移動または名前変更されたページも引き続き機能します。GitBook が古いパスからのリダイレクトを自動的に作成します。

重要な注意点：

• 既存のコンテンツを扱う場合は、まず SUMMARY.md を読んでください
• ローカルで編集した後、GitBook でテストしてください
• SUMMARY.md とファイル構造およびページタイトルを同期させてください
• OpenAPI 仕様は、Markdown に埋め込むのではなく、UI、API、MCP、または CLI からアップロードする必要があります

ブロックの使い分け

必要なもの	使用するもの	理由
順序に沿った手順	{% stepper %}	手順の流れが明確になります
選択肢（言語、プラットフォーム）	{% tabs %}	ページを煩雑にせず、ユーザーが選択できます
任意の情報や詳細情報	<details>	ページを見やすく保てます
重要な警告やヒント	{% hint %}	色付きのコールアウト（情報／警告／危険／成功）
並べて比較する情報	{% columns %}	並列レイアウト（最大 2 列）
タイムラインや変更履歴	{% updates %}	タグで絞り込める日付付きのエントリ
視覚的なナビゲーションカード	<table data-view="cards">	クリック可能なカードのグリッド
ダウンロード可能なファイル	{% file %}	キャプション付きのファイル
行動喚起リンク	<a class="button">	プライマリまたはセカンダリのボタン
ページ間で再利用するコンテンツ	{% include %}	信頼できる唯一の情報源
動的コンテンツ	<code class="expression">	変数の値を表示します

変数のスコープ：

変数の用途	定義場所	参照方法
複数のページで使用	/.gitbook/vars.yaml	space.vars.variableName
1 つのページに固有	フロントマターの vars:	page.vars.variableName

既存のコンテンツを扱う

1. まず SUMMARY.md を読む — 目次全体とファイル階層を確認します
2. SUMMARY.md がない場合 — ディレクトリ構造を直接確認します
3. .gitbook.yaml を確認する — ルートパス、カスタムの README／SUMMARY の場所、リダイレクトを確認します
4. .gitbook/assets/ を確認する — アップロードされた画像とファイルを確認します
5. .gitbook/vars.yaml を確認する — スペースレベルの変数を確認します

よくある落とし穴

スペースをまたぐリンク：

• 別のスペースにあるページへのリンクに相対パスを使わないでください。リンクが解決されません。
• /spaces/<spaceId>/pages/<pageId> は使わないでください。これは有効な GitBook のリンク形式ではありません。
• 代わりに https://app.gitbook.com/s/<spaceId>/<path> を使ってください。<path> には、ページ ID ではなく、GET /spaces/{spaceId}/content/pages から取得した対象ページの path フィールドを指定します。
• 組織 ID を含む形式の https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path> を見つけても、「修正」しないでください。これは有効なエイリアスです。2 つの形式を正規化すると、Git Sync との間で不要な差分が発生します。
• スペース ID がまだ分からない場合（新しいスペースで、まだ作成されていない場合など）は、XSPACE_<KEY> のセンチネルを使ってください。

ファイルの整理：

• SUMMARY.md で同じ Markdown ファイルを 2 回参照しないでください。
• SUMMARY.md のファイルパスと実際のファイルの場所を一致させてください。
• ページのタイトル（# 見出しまたは title フロントマター）を変更した場合は、そのページへの SUMMARY.md のリンクテキストも更新してください。リンクテキストはサイドバーのナビゲーション、ページネーション、相対リンクのテキストに使われ、自動では更新されません。ただし、SUMMARY.md の項目で、引用符付きのリンクタイトルの上書き（[Page main title](page.md "Page link title")）を意図的に使い、異なる内容を表示している場合は除きます。

設定：

• Git Sync を使用する場合、README.md の管理にはリポジトリのみを使用してください。
• ファイルを移動または名前変更した後は、リダイレクトをテストしてください。

カスタムブロック：

• ブロックは必ず適切に閉じてください（{% endtab %}、{% endhint %} など）。
• 開始タグと終了タグを正確に一致させてください。

フロントマター：

• description: の値に :、#、その他 YAML で特別な意味を持つ文字が含まれる場合は、必ず引用符で囲んでください。引用符で囲まれていない特殊文字は、エラーメッセージなしで Git Sync の失敗を引き起こすことがあります。
• ただし、出力時に引用符を必須にする必要はありません。GitBook は、折りたたみブロック（>-）を含め、シリアライザーが選択した YAML スカラー形式で説明を再出力します。記述形式ではなく、フロントマターが解析できることを検証してください（references/git-sync-serialisation.md）。
• フロントマターは必ずファイルの先頭に置いてください。

Git Sync を使用する

GitBook を Git と同期すると、変更は双方向に反映されます。Git の変更は GitBook を更新し、GitBook UI の変更は Git にコミットされます。マージコンフリクトは Git で解決します。

ベストプラクティス： 構造の変更は Git で SUMMARY.md を使って行います。重要な更新にはブランチベースのワークフローを使用します。GitBook が自動生成したコミットを確認します。

プッシュしたブランチをプレビューする

以下の 2 リンクルールは、変更リクエストを通じてプッシュされたコンテンツに適用されます。代わりに Git からプッシュする場合は、コミットステータスが同等の役割を果たします。プル／マージリクエストを開くか、すでにリクエストがあるブランチにプッシュすると、GitBook はそのブランチをインポートし、レンダリングされたサイトのプレビューへのリンクを含むステータスを投稿します。ドキュメントの変更をプッシュしたら、求められなくても必ずそのリンクをユーザーに伝えてください。 URL を自分で組み立てず、コミットステータスからリンクを取得してください。リビジョン ID はインポート時に生成され、ブランチや PR から導き出すことはできません。また、プッシュのたびに新しい ID が生成されるため、以前のリンクは古くなります。GitHub および GitLab のコマンドと、インポート中に行うことについては、references/git-sync-previews.md を参照してください。

Git Sync と変更リクエストによるコンテンツのプッシュの選択

スペースで Git Sync が設定されており、同期先リポジトリのローカルチェックアウトを持っている（または取得できる）場合は、ファイルを直接編集してコミットし、プッシュする方法を優先してください。Git Sync によって変更が GitBook に反映されます。変更リクエストのコンテンツプッシュツール（例：updateChangeRequestContent）を利用でき、接続されている MCP セッションでも同様です。ツールをすぐに呼び出せるからといって、信頼できる唯一の情報源としての Git を迂回する理由にはなりません。CR に直接プッシュできるとわかったエージェントも、実行する前に Git Sync が設定され、利用可能かどうかを確認してください。

次の場合は、変更リクエストによるコンテンツプッシュの方法（MCP の updateChangeRequestContent など、または REST の POST .../change-requests/<cr>/content エンドポイント。「cr-create」スキルを参照）を使用してください。

• スペースに Git Sync がまだ設定されていない（例：セットアップ中の新しいスペース）。
• 現在の環境でローカルの Git チェックアウトを利用できない（同期先リポジトリにファイルシステムからアクセスできない）。
• 変更が小規模かつ限定的である（誤字、段落ひとつ、フィールドひとつなど）。CR を作成するのが妥当であり、リポジトリ全体のクローン、コミット、プッシュを行うほどではありません。

新しいページツリーの作成、複数ページの書き直し、移行など、それ以上の規模の変更では、まずリポジトリがローカルにクローンされていることを確認する必要があっても、Git Sync を優先してください。最初に使えたという理由だけで、変更リクエストツールを既定の方法にしないでください。

Git Sync がロックされているスペース

スペース API で editMode: "locked" が表示され、gitSync が設定済みまたは有効な場合、GitBook UI ではそのスペースの信頼できる唯一の情報源として Git が扱われます。編集する前にこれらのフィールドを読み取り（GET /spaces/{spaceId} または同等の方法）、適切な手順を選択してください。

ロックされ、同期されているスペースのルール：

• 同期先リポジトリをチェックアウトしている場合は、コンテンツと構造の変更にgit push を優先してください（上記と同じ方針です）。チェックアウトを利用できない場合は、小規模で限定的な編集に変更リクエストを使用できます。
• Git Sync がすでに設定されている場合は、POST /spaces/{spaceId}/git/import または …/git/export を呼び出さないでください。これらのエンドポイントは 400（Cannot use git API when space has a git sync configured）を返します。インポートとエクスポートは、管理対象の同期 Webhook によって処理されます。
• git push の後は、Webhook のインポートが完了するまで待ってください。公開済みのサイトが即座に更新されたと決めつけず、スペースの Git Sync ステータス（例：GET /spaces/{spaceId}/git/info → operation.state / direction）を確認してください。ブランチプレビューの反映時間については、references/git-sync-previews.md を参照してください。
• スペース変数は /.gitbook/vars.yaml（または Library UI）にあります。変更リクエストのコンテンツ操作（updateChangeRequestContent には変数の変更機能がありません）では設定できません。Git Sync を通じて vars.yaml をプッシュするか、UI で編集してください。
• **式：**公開済みの .md では、解決済みの値はインライン展開されず、<code class="expression">…</code> がソースとして保持されます。変数や式がレンダリングされていることを確認するには、公開済みの HTML、サイトプレビュー、または GitBook UI を確認してください。.md エクスポートだけでは確認できません。
• **双方向同期：**変更リクエストをマージすると、GitHub/GitLab リポジトリにエクスポートされる場合があります。Git Sync のエクスポートで未完成の作業が上書きされないよう、ローカルでさらにコミットする前にプルするか、作業ツリーをクリーンな状態に保ってください。

変更リクエストが関係する場合は、必ず2つのリンクを提示してください

この編集の一部でも変更リクエスト（create_change_request／updateChangeRequestContent、または REST 相当の操作）を経由した場合、以下の両方を毎回報告するまで、編集は完了していません。これは絶対的なルールであり、読み飛ばしてよい注意事項ではありません。

1. CR の差分／エディターリンク — create_change_request、updateChangeRequestContent、または getChangeRequestById が返す、変更リクエストオブジェクトの urls.app。
2. サイトのプレビューリンク — Site オブジェクトのサイト URL（サイトが公開されている場合は urls.published、それ以外の場合は urls.preview）に /~/changes/<number>/ を追加したもの。これは変更リクエストのレスポンスには含まれないため、別途照会する必要があります。そのため、忘れられやすいリンクです。必要だと思ったときだけでなく、毎回取得してください。**~/changes/ の部分がなければ、そのリンクは変更リクエストのプレビューではありません。**サイトの現在のコンテンツが表示されるため、一見もっともらしく見えても誤りです。

どのスキル（このスキルまたは configure-site）がコンテンツを反映したか、どのトランスポート（MCP または REST）を使ったかにかかわらず、このルールが適用されます。詳しい説明と REST での解決手順は、cr-create スキルの「プレビューリンクの提示」を参照してください。MCP での同等の手順（GitBook MCP には、プレビューリンクを取得する単一の既成の呼び出しはありません）：

1. スペースの組織を特定します — invoke_operation("getSpaceById", {path:{spaceId}}) → .organization（組織 ID がすでにわかっている場合は省略）。
2. スペースが属するサイトを見つけます — list_sites／get_site_structure を使うか、各サイトの site-spaces を調べて .space.id が一致するものを確認します。
3. invoke_operation("getSiteById", {path:{organizationId, siteId}}) → .urls.published（サイトが公開済みの場合）、それ以外は .urls.preview。API が返す末尾のスラッシュを削除してから、/~/changes/<number>/ を追加します。

スペースが公開済みのサイトに紐付いていない場合は、その旨を明確に伝え、差分リンクのみを提示してください。説明なしにプレビューリンクの行を省略してはいけません。

このルールは、実際にすでに守られなかったことがあります。編集が反映され、マージされたにもかかわらず、報告されたのは差分リンクだけで、プレビューリンクは担当者が直接尋ねて初めて提示されました。上記の2リンクのチェックリストは文字どおりに従ってください。

参考ファイル

より詳細な情報が必要な場合は、必要に応じて以下を読み込んでください。

• references/blocks.md — すべての GitBook ブロックタイプの完全な構文と実例：タブ、ステッパー、ヒント、折りたたみ、カラム、更新情報、カード、埋め込み、ファイル、ボタン、アイコン、再利用可能なコンテンツ、OpenAPI ブロック。複雑なページを作成するときや、上記のクイックリファレンスでは不十分な場合に読み込んでください。
• references/frontmatter.md — すべてのフロントマター項目とその説明、YAML の引用符のルール、カバー画像、条件付きコンテンツ（if:）、変数と式の詳細。ページレイアウト、カバー、条件付き表示、変数を設定するときに読み込んでください。
• references/markdown.md — 標準的な Markdown、タイトル付きコードブロック、数式／TeX、Mermaid の図の種類と例、SVG の取り扱いに関する注意点。図、数式、SVG アセットを扱うときに読み込んでください。
• references/configuration.md — .gitbook.yaml のオプション、.gitbook/ ディレクトリ構成（アセット、インクルード、変数、タグ）、SUMMARY.md の完全な文法ルール。スペースの設定、リダイレクトの追加、SUMMARY.md の作成や編集を行うときに読み込んでください。
• references/git-sync-serialisation.md — GitBook がスペースをリポジトリにエクスポートする際に書き換える内容：description: のスカラー形式、スペース間リンクの URL 形式、ブロックの再シリアライズ、形式ではなく妥当性をチェックするルール。Git Sync の差分に手作業では行っていない変更が含まれている場合や、ドキュメントのフロントマターやリンクを検証するチェックやビルド手順を書く前に読み込んでください。
• references/git-sync-previews.md — Git Sync 経由でブランチにプッシュした後のプレビューリンクの取得方法：GitHub と GitLab で GitBook のコミットステータスを確認する方法、サイトのプレビューとエディターの差分を見分ける方法、インポートがまだ実行中の場合の対処方法。プルリクエスト／マージリクエストが開いているブランチにドキュメントの変更をプッシュするときは、必ず読み込んでください。