> 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/write-docs.md).

# ドキュメントの作成と編集

Gitと同期されたリポジトリ、IDE、または任意のテキストエディタで、GitBookのドキュメントページを作成、執筆、編集、整形する。GitBookのMarkdownページの作成や編集、書き込みや更新に関わるタスクで使用する

#### このスキルを使うタイミング

GitBook ドキュメントを次の方法で扱うときにこのスキルを使います:

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

#### クイックリファレンス

**GitBook コンテンツ構造**

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

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

**ファイル構成:**

```
/
  .gitbook/
    assets/              # GitBook が管理する画像とファイル
    includes/            # 再利用可能なコンテンツブロック
    vars.yaml            # スペースレベルの変数
  .gitbook.yaml          # 設定
  README.md              # ホームページ
  SUMMARY.md             # 目次
  getting-started/
    installation.md
    quickstart.md
  api-reference/
    authentication.md
    endpoints.md
```

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

```markdown
---
description: "SEO 用のページ説明"
icon: book-open
hidden: true
vars:
  page_variable: value
layout:
  width: default  # または '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>` は有効なリンク形式ではありません。org 修飾の別名 `https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path>` も同じように解決されます — 短い形式で書いてください。ただし、どちらかに対して書き換えたり lint をかけたりしないでください（`references/git-sync-serialisation.md`）。取得 `<spaceId>` から `GET /orgs/{orgId}/spaces` と `<path>` ページの `パス` フィールド（ `GET /spaces/{spaceId}/content/pages`。まだ対象スペースが存在しない新しいサイトの雛形を作成していますか？次を使います: `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>` は対象ページの `パス` フィールド（from `GET /spaces/{spaceId}/content/pages`GET /spaces/{spaceId}/content/pages
* org 修飾形式を「修正」しないでください `https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path>` 見つけたときに — それは有効な別名であり、2 つの形式を正規化すると Git Sync に不要な差分が発生します。
* 使用 `XSPACE_<KEY>` スペース ID がまだ不明な場合（新しいスペース、まだ作成されていない場合）はセンチネルを使います。

**ファイル整理:**

* SUMMARY.md で同じ Markdown ファイルを 2 回参照しないでください
* SUMMARY.md と実際のファイル位置でファイルパスを一致させてください
* ページのタイトル（その `#` 見出しまたは `title` frontmatter）を変更したら、そのページの SUMMARY.md のリンクテキストも更新してください。これがサイドバーのナビゲーション、ページ送り、相対リンクテキストを制御し、自動では更新されないためです。これを省略してよいのは、SUMMARY.md のエントリが意図的に引用付きのリンクタイトル上書き（`[ページのメインタイトル](page.md "ページのリンクタイトル")`）で、意図的に別の内容を表示する場合だけです。

**設定:**

* Git Sync を使う場合、README.md はリポジトリ経由でのみ管理してください
* ファイルの移動や名前変更後にリダイレクトをテストしてください

**カスタムブロック:**

* ブロックは必ず正しく閉じてください（`{% endtab %}`, `{% endhint %}`、など）
* 開始タグと終了タグを完全に一致させてください

**フロントマター:**

* 常に引用符で囲む `description:` を含む値は `:`, `#`、またはその他の YAML で意味を持つ文字を含む値は、引用符なしの特殊文字によりエラーメッセージなしで Git Sync が静かに失敗します
* ただし戻すときに引用符を必須にしないでください。GitBook は、シリアライザが選んだ任意の YAML スカラー形式で description を再出力し、折りたたみブロックも含みます（`>-`）。フロントマターが解析できるかを検証し、書き方は検証しないでください（`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 からは導出できません。また、プッシュするたびに新しいものが生成されるため、以前のリンクは古くなります。参照: `references/git-sync-previews.md` GitHub と GitLab のコマンド、およびインポートがまだ実行中の間に何をすべきかについて。

**Git Sync と変更リクエストによるコンテンツプッシュのどちらを選ぶか**

スペースに Git Sync が設定されていて、同期済みリポジトリのローカルチェックアウトがある（または取得できる）場合は、 **ファイルを直接編集してコミット/プッシュする方を優先してください** — Git Sync がその変更を GitBook に反映します。これは、変更リクエスト用のコンテンツプッシュツール（例: `updateChangeRequestContent`）が利用可能で接続されている MCP セッションでも同様です。ツールが 1 回の呼び出しで使えるからといって、正本である Git を迂回する理由にはなりません。それを見つけたエージェントは *できる* CR に直接 push する場合でも、その前に Git Sync が設定済みで到達可能かを確認するべきです。

代わりに change-request の content-push パスを使ってください（MCP の `updateChangeRequestContent` または同等のもの、あるいは REST `POST .../change-requests/<cr>/content` エンドポイント — を参照してください。 `cr-create` スキル）は次の場合に使います：

* space にまだ Git Sync が設定されていない場合（例：新規の space がまだセットアップ途中）、
* 現在の環境でローカルの Git checkout が利用できない場合（同期済みリポジトリへのファイルシステムアクセスがない）、または
* 変更が小さく限定的な場合（誤字、1 段落、1 フィールド）— CR を開くのが適切で、フルの clone/commit/push サイクルを行うほどではありません。

それより大きいもの—新しいページツリー、複数ページの書き換え、移行—では、たとえ先にリポジトリがローカルにクローンされているか確認するために一時停止する必要があっても、Git Sync を優先してください。最初に動いたからといって、change-request ツールを標準にしないでください。

**change request が関与する場合は、2 つのリンクが必須です**

この編集の一部でも change request（`create_change_request` / `updateChangeRequestContent`、または REST の同等手段）を通った場合、 **以下の 2 つが両方とも報告されるまで、その編集は完了ではありません。毎回です—これは厳格なルールであり、読み飛ばしてよい注意書きではありません：**

1. **CR の diff/editor リンク** — `urls.app` change-request オブジェクト上の、以下で返される `create_change_request`, `updateChangeRequestContent`、また `getChangeRequestById`.
2. **サイトのプレビューリンク** — 以下の site URL **Site** オブジェクト（`urls.published` サイトが公開されている場合は、そうでなければ `urls.preview`) に **`/~/changes/<number>/` を末尾に追加したもの**。これは change-request の応答には決して含まれません—別途取得が必要です—そのため、まさに忘れられがちです。思い出したときだけでなく、毎回解決してください。 **以下がなければ `~/changes/` このセグメントがなければ、そのリンクは change request のプレビューではありません** — サイトの現在の内容を表示するだけなので、それらしく見えても誤りです。

これは、どのスキルがコンテンツを push した場合でも（このスキルであっても `configure-site`）また、転送手段が何であっても（MCP でも REST でも）適用されます。 `cr-create` 完全な説明と REST の解決手順については、そのスキルの「Surfacing the preview link」を参照してください。 **MCP の同等手段** （GitBook MCP には、用意された単一の「プレビューリンクを取得」呼び出しはありません）：

1. space の organization を解決する — `invoke_operation("getSpaceById", {path:{spaceId}})` → `.organization` （すでに org ID を持っているなら省略）
2. space が属する site を見つける — `list_sites` / `get_site_structure`、または各 site の site-spaces を確認して `.space.id`.
3. `invoke_operation("getSiteById", {path:{organizationId, siteId}})` → `.urls.published` （site が公開済みなら）、そうでなければ `.urls.preview`。これに `/~/changes/<number>/`API が返す末尾のスラッシュを除いて付け加えます。

space がいずれの公開済み site にも紐づいていない場合は、その旨を明示し、diff リンクだけを提示してください—説明なしにプレビュー行をこっそり省かないでください。

これは実際に静かに失敗したことがあります。編集が push され merge されたのに diff リンクしか報告されず、プレビューリンクは人が直接求めたときに初めて出てきました。上の 2 リンクのチェックリストは文字どおりに扱ってください。

#### 参照ファイル

タスクでより詳細な内容が必要なときに、必要に応じてこれらを読み込んでください：

* `references/blocks.md` — すべての GitBook ブロックタイプについての完全な構文と実例：tabs、steppers、hints、expandable、columns、updates、cards、embeds、files、buttons、icons、reusable content、OpenAPI blocks。 **複雑なページを作成するとき、または上のクイックリファレンスでは不十分なときに読み込んでください。**
* `references/frontmatter.md` — 説明付きのすべての frontmatter フィールド、YAML の引用符ルール、カバー画像、adaptive content（`if:`）、および variables/expressions の詳細解説。 **ページレイアウト、カバー、条件付き表示、または変数を設定するときに読み込んでください。**
* `references/markdown.md` — 標準的な markdown、タイトル付きコードブロック、math/TeX、Mermaid の図の種類と例、SVG の扱いに関する注意点。 **図、数式、または SVG アセットを扱うときに読み込んでください。**
* `references/configuration.md` — `.gitbook.yaml` options、 `.gitbook/` ディレクトリ構造（assets、includes、vars、tags）、および SUMMARY.md の文法規則の全体。 **space のセットアップ、リダイレクトの追加、または SUMMARY.md の作成/編集時に読み込んでください。**
* `references/git-sync-serialisation.md` — GitBook が space を repo に書き戻してエクスポートするときに何を書き換えるか： `description:` scalar スタイル、cross-space link の URL 形式、ブロックの再シリアライズ、そして形式ではなく妥当性を lint するというルール。 **Git Sync の diff に誰も手作業で加えていない変更が含まれているとき、または docs の frontmatter やリンクを検証する check/build ステップを書く前に読み込んでください。**
* `references/git-sync-previews.md` — Git Sync 経由で push されたブランチのプレビューリンクを取得する方法：GitHub と GitLab で GitBook の commit status を読むこと、site のプレビューと editor diff を見分けること、まだ実行中の import を扱うこと。 **pull/merge request が開いているブランチに docs の変更を push するときは、常に読み込んでください。**


---

# 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/write-docs.md?ask=<question>&goal=<endgoal>
```

`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.