Docsbook
概要

ドキュメントサイトを管理する

このガイドでは、サイトを公開した後に行う作業について説明します。ページの変更、変更の取り消し、閲覧できるユーザーの決定、最新のコミットが反映されていないサイトの問題の診断などが含まれます。まだサイトを公開していない場合は、まず最初のドキュメントサイトを作成するから始めてください。

管理ウィジェットを開く#

サインインして自分のサイトを開きます。右下隅に管理ウィジェットが表示されます：

+----------------------+
| Your name            |
|                      |
| Select chat        > |
| Select repo        > |
| Select mode        > |
|                      |
| Settings             |
| Sign out             |
+----------------------+

アバターまたは設定をクリックして、設定パネルを開きます。このページで「設定」と表示されているものは、すべてここから始まります。

読者にはこのウィジェットは表示されません。サインアウトした訪問者には、ドキュメント、デザイン、コンテンツのみが表示され、操作項目は一切表示されません。

設定で構成できる項目#

セクション 制御内容 詳細
基本設定 ワークスペース名とデフォルトのサイト言語 —
カスタムドメイン 所有するアドレスからドキュメントを配信 カスタムドメイン
外観 ライト、ダーク、またはシステムに合わせたテーマとデフォルト設定 ブランディング
言語と翻訳 Docsbookが翻訳する言語 翻訳
プライバシーとアクセス 公開、またはパスワードや独自のIDプロバイダーで制限 非公開ドキュメント
使用状況 プロジェクト残高とソースごとの支出上限 AI利用料金
ウィジェット サイトに表示するコンテンツウィジェット コンテンツウィジェット

GitHub からページを更新#

  1. github.com でリポジトリを開きます。
  2. Markdown ファイルを開き、鉛筆アイコンをクリックします。
  3. 変更を加え、変更をコミットをクリックします。

サイトが自動的にコミットを取得します。再デプロイは必要ありません。

gitを使ってコンピューターからページを更新する#

複数のファイルを一度に変更し、それらをまとめてレビューしてもらいたい場合に使用します。

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO

エディターでファイルを編集してから、公開します。

git add docs/
git commit -m "Update the installation guide"
git push origin main

ページの削除も同じ手順です。ファイルを削除し、コミットして、プッシュします。ページはサイトとサイドバーから消えます。

ブラウザを離れずにページを編集#

ちょっとした修正なら、GitHub もローカルチェックアウトも必要ありません — 読んでいるページを編集できます。

  1. Docsbook AI チャットでプロジェクトを開き、横にプレビューを表示します（分割ビュー）。
  2. プレビューの上にあるバーをプレビューから編集に切り替えます。
  3. 変更したいブロックをクリックします。

開いたパネルでは、AI でブロックを書き換えたり、テキストを直接編集したり、短縮または拡張したり、コンテンツウィジェットに変換したり、削除したりできます。ハンドルを使ってブロックをドラッグすると移動できます。新しい順序は保存または元に戻すをクリックするまでプレビューされます。

変更ではなく何かを追加するには、2つのブロックの間の境界にポインターを移動します。プラスボタンが表示され、段落、見出し、リスト、コードブロック、引用、コールアウト、表、ウィジェットを追加できます。サイドバーの下部にあるページを追加では、タイトル、フォルダー、そしてページで扱う内容に関する任意のメモを指定して、ページ全体を作成できます。

これらの操作はすべて他の変更と同様にリポジトリにコミットされるため、ソースが唯一の信頼できる情報源であり続けます。AI によるブロックの書き換えではモデルが呼び出され、プロジェクトの残高から料金が差し引かれますが、自分でテキストを編集する場合は料金はかかりません。

公開した変更を取り消す#

アシスタントが公開した変更は、GitHubを開かずにチャットから取り消せます。

  • すぐに: 公開後にアシスタントが表示するカード（「2ファイルを更新しました」）の取り消し矢印を押します。
  • 後で: チャットヘッダーの時計アイコンを開きます。プロジェクトの最近の変更と、それぞれで変更されたファイルが一覧表示され、各項目の横に取り消しボタンがあります。

この履歴はリポジトリの実際の公開履歴であるため、以前のセッションで行われた変更、チームメイトが行った変更、GitHubで直接行われた変更も一覧表示されます。どの変更も同じ方法で取り消せます。

取り消しは履歴を書き換えるのではなく、ファイルを元に戻す新しいコミットです。一覧には取り消しとマークされた独自の項目として表示され、それ自体も取り消すことができ、他のユーザーのコミットが破棄されることはありません。ファイルの以前のバージョンを読み戻せない場合は、推測せずにスキップとして報告されます。

アシスタントに改善点を尋ねる#

アシスタントに修正すべき点を尋ねましょう。「最初に何を修正すべき？」「これを検索で見つけられるようにして」「このページの内容は薄く感じる」といった質問をすると、手作業で対応しなければならない文章ではなく、チェックしていけるリストとして回答が返ってきます。

各行には、実際のページの1つに対する具体的な変更が1つずつ示されます。何が変わるのか、なぜ役立つのか、どのページが対象なのかを確認できます。書き換えではなく設定の変更を示す行もあり、その設定を切り替えるカードが開きます。最初は何もチェックされていません。必要な行をチェックして適用を1回押すと、チェックしたすべての行が一度に処理されます。チェックしていない行が書き換えられることはありません。

このリストは推測で作られるものではありません。アシスタントは、質問内容に関連するドキュメントスキル（検索とインデックス登録、文体、アクセシビリティ、翻訳など）を読み、サイトについて測定できる内容を確認し、利用可能な設定カードを確認したうえで、その結果に基づいて提案します。適用したスキルの名前も示します。

適用で実行される内容は、自動モードによって異なります。

自動モード 「適用」で実行される内容
オフ（デフォルト） 変更内容が変更前と変更後の差分として返され、ページごとに承認または却下できます
オン 変更がすぐに書き込まれて公開され、何が変わったかの概要が表示されます
選択した設定 チャット内でその設定のカードが開き、自分でスイッチを切り替えます

リストの作成とページの書き換えにはどちらもAIモデルが使用されるため、プロジェクトの残高から料金が差し引かれます。

サイドバーの順序を理解する#

Docsbook はファイル名を読み取り、サイドバーの順序を決めます。

  • 読者が読み始めるページ — README、introduction、getting-started、quick-start、installation、setup — は最初に表示されます。
  • 情報を調べるためのページ — reference、api、changelog、faq、troubleshooting — は最後に表示されます。
  • その他のページは、その間にアルファベット順で並びます。フォルダーも、フォルダー名に基づいて同じように順位付けされます。

したがって、数字の接頭辞も引き続き機能します。1-basics.md はアルファベット順で 2-intermediate.md より前に並び、Docsbook が名前を上記2つのリストと照合する際には数字が無視されます。

どのページもいずれのリストにも一致しない場合、サイドバーは単純なアルファベット順になります。ファイル名を変更すると、位置を移動できます。

ファイルをフォルダーに整理する#

サイドバーはフォルダー構造を反映するため、構造がナビゲーションになります。トピックごとにグループ化しましょう。

docs/
├── README.md
├── getting-started.md
├── api/
│   ├── overview.md
│   ├── auth.md
│   └── endpoints.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

難易度ごとにグループ化するよりも、トピックごとにグループ化する方が効果的です（1-basics.md、2-advanced.md）。読者はレベルではなく、知りたいテーマを検索エンジンで検索して訪れるからです。

通常の相対 Markdown リンクを記述します。Docsbook は公開時にそれらをサイト URL に変換します。

[Set up a custom domain](/docsbook-io/docs/guides/advanced/custom-domain)
[Create your first site](/docsbook-io/docs/guides/getting-started/creating-docs)
[Frequently asked questions](/docsbook-io/docs/faq)

アンカーを使用して同じページの見出しにリンクします。

[Jump to the sidebar order](#understand-the-sidebar-order)

アンカーは、見出しテキストを小文字にし、スペースをハイフンに置き換えたものです。そのため、リンク先として機能させるには見出しが存在している必要があります。

画像を追加する#

  1. 画像ファイルをページのそばにあるリポジトリに配置します。たとえば、images/ フォルダーに入れます。
  2. コミットします。
  3. 相対パスで参照し、画像の内容を説明します：
![GitHub fork dialog with the Create fork button highlighted](https://raw.githubusercontent.com/docsbook-io/docs/main/guides/getting-started/images/fork-dialog.png)

PNG、JPG、GIF、WebP はすべて表示できます。情報を伝えるすべての画像には、実際の代替テキストを記述してください。代替テキストは、スクリーンリーダーが読み上げる内容であり、検索エンジンがインデックスに登録する内容であり、ファイルの読み込みに失敗したときに読者に表示される内容です。

ドキュメントを読めるユーザーを管理する#

デフォルトでは、Docsbook サイトは公開されています。リンクを知っている人は誰でも閲覧でき、検索エンジンのクローラーがインデックスに登録し、GitHub アカウントも必要ありません。これは、ソースリポジトリが非公開の場合でも同様です。

非公開にするには、設定 → プライバシー & アクセスでワークスペースを非公開に切り替えます。閲覧者は、共有パスワードを使うか、独自の OIDC アイデンティティプロバイダーを介してサインインしてロックを解除する必要があります。クローラーも例外ではありません。所有者であるあなたは、常にアクセスできます。詳しい設定方法: ドキュメントサイトを読めるユーザーを制限する。

他の人と共同作業する#

GitHub経由。 リポジトリのコラボレーターとして追加します。コラボレーターはファイルを編集したり、プルリクエストを作成したりでき、変更がデフォルトブランチに反映されるとサイトが更新されます。すでにリポジトリで作業している人には、この方法が適しています。

AIチャット経由。 チャットツールバーの招待を押して、メール招待またはリンクを送信します。コラボレーターは同じライブセッションに参加するため、GitHubアカウントは必要ありません。コラボレーターの作業には、あなたと同じプロジェクト残高が使われます。

更新されていないサイトを修正する#

次の手順を順番に実行してください。

  1. コミットがGitHubに到達したことを確認します。 リポジトリを開いて、コミットを探します。そこにない場合は、まだプッシュされていません。
  2. ブラウザーのキャッシュを無視して再読み込みします。 Ctrl+F5、macOSではCmd+Shift+Rを押します。キャッシュが原因かどうかをすばやく確認するには、プライベートウィンドウを使用します。
  3. 数分待ちます。 公開はすぐには行われません。Docsbookはキー入力のたびではなく、定期的にリポジトリを確認します。
  4. ファイル拡張子を確認します。 .md ファイルのみが公開されます。
  5. ファイル名を確認します。 ラテン文字、数字、ハイフンは安全に使用できますが、その他の文字ではURLが生成されない場合があります。

一部のページは更新され、他のページは更新されていない場合、ほとんどの場合、原因は同期ではなくブラウザーのキャッシュです。部分的な更新は、Docsbookが公開する状態ではありません。

バージョン管理#

Docsbook はドキュメントの 1 つのバージョン、つまりブランチの現在の状態を提供します。複数の公開バージョンを横並びで表示することは、現在サポートされていません。

今すぐ必要な場合は、バージョンを別々のブランチ（docs/v1、docs/v2）または別々のリポジトリに保持し、公開したいものを接続してください。

誰が読んでいるかを確認する#

Float Widget → Analyticsを開きます。ページごとに閲覧数、訪問者数、人気のページ、参照元、検索クエリがレポートされるため、どのページがトラフィックを獲得しているか、どのページが読まれずにいるかを確認できます。

ページに関するほとんどの疑問には、2つのレポートで答えられます。トラフィックについてはウェブ分析、訪問した読者が必要な情報を得られたかどうかについてはページフィードバックをご利用ください。

ワークスペースを削除#

設定 → ワークスペースを削除すると、ドキュメントサイトとそのすべての設定が削除されます。この操作は元に戻せません。

GitHubリポジトリには影響ありません。Markdownはこれまでどおり元の場所に残るため、ワークスペースを削除しても失われるのは設定であり、コンテンツではありません。

次のステップ#

Updated

このページは役に立ちましたか？

提供： Docsbook