> 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/docs-as-code/git-sync/content-configuration.md).

# コンテンツ設定

コード経由で Git Sync を設定する

Git Sync は 3 つのファイルを使用します。必要な Git Sync の部分を制御するファイルを選択してください:

* `gitbook-docs.yaml` サイトを構成し、スペースをリポジトリ内のディレクトリに対応付けます。
* `.gitbook.yaml` GitBookが1つのスペースのコンテンツを読み取る方法を構成します。
* `SUMMARY.md` スペースのナビゲーションを定義します。

### gitbook-docs.yaml でサイトを構成する

`gitbook-docs.yaml` サイト全体を構成します。Git Syncプロジェクトのディレクトリに配置します。Project directoryを設定していない場合、GitBookはリポジトリのルートを使用します。 **プロジェクトディレクトリ**.

次を使用して、 `gitbook-docs.yaml` サイト構造を定義し、各スペースをディレクトリに対応付けます。 `site.structure` の各項目には、変更されない `key`があります。スペースの `content.directory` は、そのスペースのリポジトリ内のディレクトリを指定します。サイト内のスペースがサイトのリポジトリに同期されない場合、その値は `content.directory` となります。 `null`.

#### サイトとスペースの構成を理解する

`gitbook-docs.yaml` サイト全体の構成とディレクトリのマッピングを管理します。 `.gitbook.yaml` マッピングされた1つのスペースのコンテンツを設定します。

両方のファイルがある場合、GitBookは `gitbook-docs.yaml` を先に適用して、スペースのディレクトリを選択します。 `.gitbook.yaml` はその後、そのディレクトリ内のコンテンツを設定します。サイトレベルの `content.directory` のマッピングを上書きすることはできません。

#### キーはスペースを識別します

Git Syncは、各スペースとセクションをタイトル、パス、ディレクトリではなく、 `key`で識別します。このキーを使って、GitBookは `gitbook-docs.yaml` 内のエントリを、次回以降の同期で既存のコンテンツと照合します。

{% hint style="danger" %}
**スペースの `key` を変更すると、そのスペースは置き換えられます。** GitBookは古いキーを削除されたもの、新しいキーを新しいスペースとして扱います。新しいスペースを作成し、対応付けられたディレクトリからコンテンツをインポートします。元のスペースは組織内に残りますが、サイトから切り離されます。

ページは戻ってきますが、新しいスペース ID を持つ別のスペースに入ります。古い ID を参照するリンク、カード、API 呼び出しは解決されなくなり、GitBook 内にのみ存在しリポジトリには存在しないものは元のスペースに残ります。

元のキーを復元しても、これは元に戻りません。別の新しいスペースが作成され、そこにインポートされます。
{% endhint %}

エントリを最初に作成するときはキーを自由に選んで安全であり、GitBook はサイト コンテンツのマッピングを保存するときにキーを生成します。スペースが公開されたら、そのキーは永続的なものとして扱ってください:

* スペースの名前を変更するには、 `title`を変更します。キーは変わりません。
* スペースのURLを変更するには、 `path`を変更します。キーは変わりません。

この例では、英語とフランス語のスペースを別々のディレクトリにマップしています:

{% code title="gitbook-docs.yaml" expandable="true" %}

```yaml
$schema: https://api.gitbook.com/gitbook-docs.yaml
site:
  title: ドキュメント
  structure:
    - type: section
      key: documentation
      title: ドキュメント
      path: documentation
      children:
        - type: space
          key: docs-en
          title: 英語
          path: docs
          default: true
          content:
            directory: ./docs/en
            language: en
        - type: space
          key: docs-fr
          title: フランス語
          path: fr
          content:
            directory: ./docs/fr
            language: fr
```

{% endcode %}

<details>

<summary>追加のサイト プロパティを構成する</summary>

これらのオプション プロパティを使ってサイト構造を細かく設定します:

| プロパティ                  | 用途                                  |
| ---------------------- | ----------------------------------- |
| `type: section-group`  | 関連するセクションを共有のナビゲーション見出しの下にまとめます。    |
| `description`          | セクションに説明を追加します。                     |
| `icon`                 | セクションまたはセクショングループにアイコンを追加します。       |
| `localizedTitle`       | セクション、セクショングループ、またはスペースのタイトルを翻訳します。 |
| `localizedDescription` | セクションの説明を翻訳します。                     |
| `hidden`               | サイト ナビゲーションからスペースを非表示にします。          |

サイトのコンテンツマッピングを保存するとき、GitBookは `gitbook-docs.yaml` を作成または更新します。

</details>

### .gitbook.yaml でスペースを構成する

`.gitbook.yaml` 1つのスペースを構成します。対応付けられたスペースのディレクトリに配置します。コンテンツのルート、最初のページ、ナビゲーションファイル、リダイレクトの設定に使用します。

たとえば、スペースが `./docs`にマッピングされている場合は、ファイルを `./docs/.gitbook.yaml` に配置し、 `root: ./` のままにします。ただし、コンテンツがさらに下の階層にある場合は除きます。スペースがリポジトリのルートにマッピングされ、そのコンテンツが `./docs`にある場合は、 `.gitbook.yaml` をリポジトリのルートに配置し、 `root: ./docs/`.

主な設定は次のとおりです:

* `root` GitBookが読み取るディレクトリを指定します。既定値は `./`.
* `structure.readme` 最初のページを指定します。既定値は `README.md`.
* `structure.summary` ナビゲーションファイルを設定します。デフォルトは `SUMMARY.md`.
* `redirects` スペース内の古いパスを新しいパスに対応付けます。

一般的な構成例です:

{% code title=".gitbook.yaml" %}

```yaml
root: ./

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

redirects:
  previous/page: new-folder/page.md
```

{% endcode %}

#### コンテンツ ルートを設定する

コンテンツがサブディレクトリ内にある場合は、 `root` を設定します。

{% code title=".gitbook.yaml" %}

```yaml
root: ./docs/
```

{% endcode %}

{% hint style="warning" %}
.gitbook.yaml `内のパスは` を基準とした相対パスです。 `root`。たとえば、 `root: ./docs/`, `structure.summary: ./product/SUMMARY.md` は次のパスに解決されます。 `./docs/product/SUMMARY.md`.
{% endhint %}

モノレポでは、 `root` は、マッピングされたスペースディレクトリ内でのみ適用されます。兄弟ディレクトリが利用可能になるわけではありません。複数のスペースを含むリポジトリの設定については、 [モノレポ](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync/monorepos.md).

#### 最初のページとナビゲーション ファイルを設定する

を参照してください。 `structure.readme` と `structure.summary` を使って、ファイルパスをカスタマイズします。

{% code title=".gitbook.yaml" %}

```yaml
structure:
  readme: ./product/README.md
  summary: ./product/SUMMARY.md
```

{% endcode %}

{% hint style="warning" %}
Git Sync が有効な場合は、リポジトリ内の `README.md` ファイルを管理してください。GitBook で編集すると、競合やページの重複が発生することがあります。
{% endhint %}

#### リダイレクトを構成する

スペースレベルのリダイレクトは `.gitbook.yaml`で設定します。リダイレクトのパスは、そのスペース内でのみ適用されます。

GitBook アプリでサイトレベルのリダイレクトを管理することもできます。詳しくは、 [サイトのリダイレクト](https://gitbook.com/docs/documentation/ja-gitbook-documentation/publish/site-redirects.md).

### SUMMARY.md でナビゲーションを構成する

`SUMMARY.md` はスペースの目次を定義します。GitBook は、設定された `root` ディレクトリ内でこのファイルを探します。

GitBook が `SUMMARY.md`を見つけられない場合、フォルダーと Markdown ファイルからナビゲーションを推定します。GitBook でナビゲーションを変更すると、 `SUMMARY.md` が作成または更新されます。

ページグループにはレベル2の見出しを、子ページにはネストされたリンクを使用します。ページグループ見出しの後にあるすべての最上位リンクは、次のページグループ見出しまでそのグループに属します。水平線ではグループは閉じられないため、グループ化されていない最上位ページは最初のグループの前に配置します：

{% code title="SUMMARY.md" %}

```markdown
# 概要

## プロダクト

* [概要](README.md)
  * [始め方](getting-started.md)
  * [設定](configuration.md)

## リファレンス

* [API リファレンス](api.md)
```

{% endcode %}

各 Markdown ファイルは、 `SUMMARY.md`内に1回だけ記載できます。1つのスペース内で、ページに設定できる URL は1つだけです。

#### ナビゲーション ラベルを設定する

ナビゲーション ラベルがページタイトルと異なる場合は、ページリンクのタイトルを追加します:

{% code title="SUMMARY.md" %}

```markdown
# 概要

* [ページのメインタイトル](page.md "ナビゲーションラベル")
```

{% endcode %}

GitBook はサイドバー、ページネーション、相対リンクでリンクタイトルを使用します。ページのスラッグや URL は変更されません。リンクタイトルがない場合、GitBook はページタイトルを使用します。

#### 絶対 URL へのリンク

`SUMMARY.md` では、外部ページや別のスペースへのナビゲーションに絶対URLを使用できます。

{% code title="SUMMARY.md" %}

```markdown
# 概要

* [GitBook](https://gitbook.com)
* [API リファレンス](https://app.gitbook.com/s/<spaceId>/api-reference)
```

{% endcode %}

別のスペース内のページにリンクするには、絶対形式のGitBook URLを使用します。 `<spaceId>` をリンク先のスペースIDに置き換えてください。


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync/content-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
