> 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/rifarensu/concepts.md).

# 基本概念

GitBookの基本を学び、ユーザー向けの優れたドキュメントを作成・公開できるようにする

<div data-full-width="false"><figure><picture><source srcset="https://4217681718-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-c8fbd83e198347ff1386b0c4517e61c97a6d4db6%2F25_12_10_editor_and_block_palette.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://4217681718-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-5274ea5cac7b60eeb7e4dd89a52f25496b9c3e2a%2F25_12_10_editor_and_block_palette_1.png?alt=media" alt="An illustration showing the block palette open in the GitBook editor. The window is floating on a pastel yellow and pink background"></picture><figcaption></figcaption></figure></div>

## コンテンツの整理

### セクション <a href="#space" id="space"></a>

セクションとは、関連するページのセットに取り組むためのプロジェクトです。セクション内では、コンテンツを作成し、ページグループやサブページでページを整理し、連携機能をインストールするなど、さまざまなことができます。

セクションは docs サイトに属しており、docs サイトには好きなだけセクションを追加できます。つまり、コンテンツを作成するときに、製品ドキュメント、API リファレンス、更新履歴、ヘルプセンターなど、ドキュメントに含めたいものごとに別々のセクションを作成し、それらをすべて 1 つの docs サイトに公開できます。

主要なドキュメントの翻訳版や、製品の異なるバージョンごとの別個の docs を作成したい場合もあるでしょう。これらはいずれも独自のセクションを持ち、ユーザーが閲覧できるように 1 つの docs サイトに追加できます。

#### グループ <a href="#collection" id="collection"></a>

グループは GitBook アプリ内のフォルダのように機能し、関連するセクションをまとめておくことで、コンテンツを整理・保管しやすくします。

コンテンツを整理しやすくするだけでなく、グループはコンテンツ単位の権限を大規模に管理するのも容易にします。複数のセクションをグループに追加してグループ全体の権限を設定することで、組織レベルの権限を上書きできます。

### docs サイト

コンテンツを docs サイトとして公開できます。あなたの docs は、独自のブランディング、分析、カスタムドメインでカスタマイズできる Web サイトとして、選択した対象読者に公開されます。

ドキュメントサイトは必要なだけ作成できます。すべて組織の **ホーム**に一覧表示されます。サイトを開くと、サイトのサイドバーから設定やカスタマイズオプションを変更できます。

サイト上のコンテンツは、そのセクション内にあります。新しい docs サイトを作成すると、新しいセクションを作成するか、既存のコンテンツを追加できます。docs サイトには、1 つのセクションだけを含めることも、翻訳や以前の製品バージョンを含む、異なるコンテンツを含む複数のセクションを含めることもできます。

## コンテンツの編集

GitBook のビジュアルエディタでは、WYSIWYG（見たまま編集）インターフェースを使ってセクションにコンテンツを追加できます。

編集はデスクトップおよびノートパソコンで利用できます。スマートフォンでは組織やコンテンツを閲覧できますが、編集にはデスクトップまたはノートパソコンが必要です。

### ページ

ページは、コンテンツを追加、編集、埋め込む場所です。ページは常にセクション内にあり、セクションには好きなだけページを追加できます。

セクション内のページは、エディタ左側の目次に表示されます。ここでは、新しいページを追加したり、ページグループを作成したり、ページを別のページの下に入れ子にしてサブページを作成したりできます。

{% hint style="info" %}

#### ページを編集または追加する方法がわかりませんか？

サイトが公開されている場合、セクションのコンテンツを変更するには、事前に変更リクエストを作成する必要があります。 [変更リクエストについては、以下をご覧ください](#change-requests).
{% endhint %}

### ブロック

GitBook はブロックベースのエディタです。つまり、標準的なテキストや画像から、より高度でインタラクティブなブロックまで、さまざまな種類のブロックをページに追加できます。ページには必要なブロックの組み合わせを自由に含められ、1 ページに配置できるブロック数に制限はありません。

ブロックベースの編集では、ドラッグ＆ドロップでコンテンツを簡単に再配置したり、既存コンテンツの途中に新しいブロックを追加したりできます。エディタのインターフェースを使って新しいブロックを作成することも、Markdown を使ってブロックを作成・書式設定することもできます。

GitBookで使用できるすべてのブロックについては、 [「ブロック」セクションをご覧ください](https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/blocks.md).

#### Markdown の編集

GitBook のエディタでは、Markdown を使ってコンテンツブロックを作成し、書式設定できます。

Markdown は、そのシンプルさで広く知られている人気のマークアップ構文です。GitBook では、リッチで構造化されたテキストをキーボード中心で書く方法として Markdown をサポートしており、GitBook のすべてのブロックを Markdown 構文で記述できます。

{% hint style="info" %}
Markdown自体について詳しくは、 [CommonMark](https://commonmark.org/help/).
{% endhint %}

### Git Sync

Git Sync を使うと、チームは GitHub または GitLab リポジトリを GitBook と同期し、Markdown ファイルを美しく使いやすい docs に変換できます。一度設定すると、GitBook アプリとコードベースの間で、すべてのコンテンツが同期された状態に保たれます。

Git Sync は双方向なので、GitBook のビジュアルエディタで行った変更は自動的に同期され、GitHub または GitLab で行われたコミットも同様に同期されます。これにより、開発者は GitHub または GitLab から直接コミットでき、他のチームメンバーは GitBook 内で直接変更を編集し、フィードバックを残せます。

Git Syncを使うと、一括変更やlintなど、GitBookのドキュメントで役立つさまざまなワークフローも利用できます。詳しくは [Git Syncセクションをご覧ください](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync.md).

## 編集の流れ

### 変更リクエスト

変更リクエストとは、メインコンテンツの [**ブランチ**](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) で、バージョン履歴を維持しながら並行して編集を行うために使用できます。GitHubのプルリクエストやGitLabのマージリクエストを使ったことがある方には、なじみのある仕組みです。

公開済みの docs サイトのコンテンツを編集したい場合は、まずセクションで変更リクエストを開く必要があります。

変更リクエストでは、セクション内のコンテンツを追加、編集、削除し、その後チームにレビューを依頼して、変更をメインコンテンツにマージし、公開済みの docs サイトを更新できます。

{% hint style="info" %}

#### ブランチングの概要

変更リクエストを開くと、その特定の時点でのコンテンツのコピーが作成され、これを「ブランチ」と呼ぶこともあります。変更リクエストをマージするまで、加えた変更はメインコンテンツには表示されません。

ブランチングの利点は、チームメイトがあなたと同時にそれぞれの変更リクエストを作成、編集、マージできるため、お互いの作業を邪魔しないことです。もし誰かがあなたと同じコンテンツを編集した場合でも、GitBook はマージ前に競合の解決を案内してくれます。
{% endhint %}

#### レビュー

レビューは確認作業を促し、ドキュメントの品質と正確性の向上に役立ちます。

マージして docs サイトで変更を公開する前に、変更リクエストにレビューを依頼できます。変更リクエストにタイトルと説明を追加すると、レビュー担当者に文脈が伝わります。

レビュアーは、変更リクエストの差分を表示して、新しく追加されたもの、変更されたもの、削除されたものをすべて確認できます。組み込みのコメント機能を使ってページ上で直接フィードバックを残すこともでき、その後、変更リクエストを承認するか、さらに変更を求めることができます。

#### マージ

変更リクエストをマージすると、その変更リクエスト内のすべてのコンテンツがメインのコンテンツブランチに追加され、その変更は docs サイトにも公開されます。

変更リクエストをマージすると、セクションのバージョン履歴に新しいバージョンも作成されます。

## ドキュメントの公開

コンテンツを [ドキュメントサイト](#docs-site)として公開すると、サイトにコンテンツを追加したり、対象ユーザーを変更したり、デザインやその他の設定をカスタマイズしたりできます。

### docs サイトの構造化

サイトに追加コンテンツを入れたい場合、用途の異なる 2 つの選択肢があります。セクションとバリアントです。

#### サイト構造内のセクション <a href="#site-section" id="site-section"></a>

セクションを使うと、 **1つのドキュメントサイトに複数の種類のドキュメントを追加できます**。たとえば、このドキュメントサイトのように、1つのサイトで製品ドキュメント、APIリファレンス、ヘルプセンター、変更履歴をまとめて公開できます。

新しいセクションを追加すると、サイト上部のナビゲーションバーに各セクションの項目が追加されます。また、セクションを [グループ](#collection) にまとめてナビゲーションバーにドロップダウンメニューを作成することもできます。サイトに階層構造を設けるのに最適です。

#### バリアント

バリアントを使うと、 **同じドキュメントの複数のバージョンを1つのドキュメントサイトに追加できます**。たとえば、ドキュメント全体を複数の言語に翻訳したり、まだ更新していないユーザー向けに製品の旧バージョンを記録したりできます。

エンドユーザーは、サイト左側の目次上部にある言語ピッカーまたはバリアントピッカーを使って、これらのバリアントを切り替えられます。

<div data-with-frame="true"><figure><img src="https://4217681718-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-b13c3123b0d22ce9fce674e4d650a32ac78b5078%2F25_12_10_structure_light.png?alt=media" alt="A screenshot of the Roboflow Documentation site, with a navigation bar along the top and an open drop-down menu at the top of the table of contents showing different language variants for the site."><figcaption><p>セクションはサイト上部にナビゲーションバーを作成し、ユーザーは目次内のメニューを使ってバリアントを切り替えます。</p></figcaption></figure></div>

### サイトの閲覧者

公開時に誰にドキュメントを見せるかを選択できます。新しいサイトの既定値は公開され、検索エンジンにインデックスされることです。

ただし、サイトにアクセスできるユーザーをより細かく管理したい場合は、 **共有リンク** または **認証済みアクセス**.

共有リンクを使うと、プライベートリンクを作成して相手に直接共有するだけで、組織に招待することなく、顧客やパートナーとコンテンツを非公開で共有できます。リンクを持っている人なら誰でも、サイトにアクセスできます。

さらに厳密に制御したい場合は、認証付きアクセスを使うことで、閲覧には訪問者の認証を必要としながらコンテンツを公開できます。有効にすると、GitBook はどのユーザーがコンテンツにアクセスできるかを認証プロバイダーに任せます。これは、プライベートコンテンツや、チームメンバーだけがアクセスできる社内ナレッジベースの公開に最適です。

を使って、対象ユーザーを制限できます。また、アダプティブコンテンツ機能を使うと、個々のページやブロックを閲覧できるユーザーも制御できます。設定すると、指定したユーザー属性に基づいてコンテンツの表示・非表示が切り替わります。詳しくは [アダプティブコンテンツのページをご覧ください](https://gitbook.com/docs/documentation/ja-gitbook-documentation/publish/adaptive-content.md).

### サイトのカスタマイズ

GitBook には、docs サイト向けの組み込みカスタマイズオプションが用意されており、ドキュメントの見た目や雰囲気を製品やブランドに合わせやすくなっています。

カスタマイズを一切適用しなくても、docs はそのままで十分見栄えがします。しかし、ロゴ、アイコン、色をカスタマイズしたり、カスタムフォントを追加したり、docs を製品と同じくらい魅力的に見せる組み込みテーマを選んだりできます。

<div data-with-frame="true"><figure><img src="https://4217681718-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-b5176c44bacdad5f68cf9d1e7801920a2d8446dc%2F25_07_16_customization_demo.png?alt=media" alt="An illustration showing five docs sites hosted in GitBook, each with distinct visual customizations"><figcaption><p>独自のロゴ、色、フォント、画像などを使って、ブランドに合わせてドキュメントをカスタマイズできます。</p></figcaption></figure></div>

### SEO と AI 向けの最適化

GitBook で公開されたドキュメントは、検索（SEO）と、ChatGPT、Claude、Google AI Overview（GEO）などの AI システム向けに自動的に最適化されます。これらはバックエンドで処理されるため、必要なのは、狙いたいキーワードや用語を含むコンテンツを書くことだけです。

ページは各ページのタイトルと説明からメタデータを取得し、コンテンツはレスポンシブになるように整形されます。GitBook は目次に基づいてサイトマップを自動生成し、ページはキャッシュされてグローバル CDN 経由で配信されるため、パフォーマンスが向上します。これらすべてが、検索エンジンでの高い順位付けに役立ちます。

同様に、GitBook は急速に進化する業界標準に従って AI ツール向けの最適化も行います。

GitBook はすべてのページの .md 版を自動的に作成するため、大規模言語モデル（LLM）が解析しやすくなります。また、公開されているすべてのサイトで MCP（Model Context Protocol）サーバーを自動的に公開し、AI ツールがスクレイピングなしでリソースとしてドキュメントを構造化された方法で検出・取得できるようにします。さらに、サイトでは `llms.txt` と `llms-full.txt` も生成され、AI による取り込みを想定して設計されています。

## チーム管理

### 組織

GitBook の組織には、個々の会社のすべてのコンテンツと docs サイトが含まれます。1 つのアカウントで、1 つまたは複数の組織のメンバーになれ、サイドバー上部の組織メニューを使って切り替えられます。

### メンバー

メンバーは組織内の個々のユーザーです。組織には好きなだけメンバーを追加でき、それぞれに固有のアクセス要件に合わせた権限を付与できます。

メンバーアカウントは個人に紐づいており、共有してはいけません。代わりに、共同作業者をそれぞれ招待し、適切なロールを割り当ててください。アカウントの保護やサインイン時の復旧方法については、 [個人設定](https://gitbook.com/docs/documentation/ja-gitbook-documentation/akauntoto/account-settings.md#account-protection-and-sign-in-recovery).

#### 権限

権限を使うと、組織メンバーのアクセスレベルを決められます。メンバーが組織に参加すると、Editor や Reader などの役割を割り当てます。これらの役割が、組織内のすべてのコンテンツに対する権限を定義します。ただし、コンテンツ単位でこれらの権限を上書きすることもできます。たとえば:

* Reader ロールの人に、ある特定のコンテンツ 1 件への編集アクセス権を付与できます
* 特定の機密またはプライベートなコンテンツへのアクセスを制限し、組織内の特定メンバーのみにアクセス権を付与できます。

詳しくは、 [「権限と継承」ページをご覧ください](https://gitbook.com/docs/documentation/ja-gitbook-documentation/collaborate/member-management/permissions-and-inheritance.md).


---

# 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/rifarensu/concepts.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.
