GitBookへの記事公開
個人用アクセスキーを使用してGitBookを接続し、Cleveraの記事をGitBookスペースのページとして公開します。キーの作成場所、サイトの選択、ヒント・ステップ・タブの変換方法、更新時の動作、および一般的なエラーについて説明します。
Cleveraの記事をGitBookスペースのページとして公開します。GitBookはサインインではなく個人用アクセスキーを使用して接続され、ページは選択したスペースの最上位レベルに作成されます。
始める前に
- Clevera: ワークスペースがProまたはカスタムプランである必要があります。また、GitBookを接続するにはオーナーまたは管理者の権限が必要です。接続後は、記事の編集権限を持つユーザーであれば誰でも公開できます。他のツールへの記事公開を参照してください。
- GitBook: すべてのプランで利用可能です。キーは作成したGitBookユーザーとして機能するため、そのユーザーには公開先のスペースに対する編集権限が必要です。
- 記事: まず記事を作成してください。公開時には記事のみが送信されます。動画を含める場合は、記事内に配置してください。記事内で動画を表示するを参照してください。
GitBookアクセスキーを作成する
- GitBookでアカウント設定を開き、Developer (
app.gitbook.com/account/developer) に移動します。 - 新しい個人用アクセストークンを作成し、「Clevera」などの名前を付けてコピーします。GitBookで表示されるのは一度だけです。
GitBookを接続する
接続ウィンドウを開く
Cleveraでサイドバーのワークスペース名をクリックし、連携を選択します。GitBookを見つけて接続をクリックしてください。「アクセスキーを貼り付けてください。保存前に確認を行います。」と表示されたGitBookを接続ウィンドウが開きます。DeveloperページへのGitBookを開くリンクも用意されています。
キーを貼り付けて確認する
アクセスキーにキーを貼り付け、キーを確認をクリックします。GitBookで承認されると「キーが承認されました。」と表示されます。
サイトを選択する
公開先サイトの下に、Cleveraがドキュメントサイト（またはスペース）の一覧を表示し、すべてを選択状態にします。リストを開いて不要なサイトのチェックを外す（例：「3件中2件を選択」）などしてから、接続をクリックしてください。「GitBookが接続されました。」と表示されます。
Cleveraは保存前にキーを確認します。
GitBookアカウントにスペースが全くない場合、Cleveraは最初の組織内に「Clevera」という名前のスペースを自動作成し、すぐに公開できるようにします。
キーはClevera側では期限切れになりません。キーやサイトを変更するには、GitBook接続の**⋯**メニューを開き、再接続を選択して同じウィンドウで操作を行ってください。新しいキーと選択内容が古いものと置き換わります。
GitBookに記事を公開する
公開タブを開く
エディターで共有 → 公開をクリックし、公開の準備ができましたの下にあるGitBookタイルをクリックします。
スペースを選択する
公開先の下に、選択したサイトに対応するスペースがアイコン付きで表示されます。
公開する
GitBookへ公開をクリックします。Cleveraはまず既存のコピーを探します。同じタイトルのページがスペース内に既に存在する場合は、対処方法を選択してください（公開済みページを更新するを参照）。完了すると「GitBookに公開されました。」と表示されます。GitBookで開くをクリックしてページを確認してください。
処理中に共有ウィンドウを閉じても問題ありません。完了すると通知が届きます。
ページはスペースの最上位レベルに追加され、そのアドレスはタイトルから生成されます（例：「Set up billing」は /set-up-billing になります）。他の言語のタイトルやアクセント記号付きのタイトルは、まずラテン文字に変換されます。変換できないタイトルには短い固定コードが割り当てられます。公開後、GitBook上でページの移動や名前変更を行うことも可能です。
GitBookでのページの見た目
ページタイトルは記事のタイトルになります。ページには記事の内容のみが含まれ、記事の元となった動画は追加されません。
| Clevera内 | GitBook内 |
|---|---|
| 見出し、段落 | 見出しとテキスト |
| 太字、斜体、取り消し線、インラインコード、リンク | 保持 |
| ハイライト、上付き文字、下付き文字 | 保持 |
| 箇条書き、番号付きリスト、チェックリスト | リストとタスクリスト |
| 引用 | 引用 |
| コードブロック | 言語とコードタイトル付きのコードブロック |
| 区切り線 | 区切り線 |
| テーブル | 各セルのテキストを含むテーブル |
| コールアウト | ヒントブロック：info → Info、note → Info、tip → Success、success → Success、warning → Warning、danger → Danger |
| 番号付きステップ | GitBookのステッパー（ステップごとに1つ） |
| タブ | GitBookのタブ |
| 折りたたみセクション | 展開可能なブロック |
| カード | 説明付きのリンクリスト（カードアイコンは除外） |
| 数式 | GitBookの数式 |
| スクリーンショット | キャプション付きでスペースにアップロードされた画像 |
| 記事内の動画や埋め込み | 埋め込みブロック。Cleveraの動画は、その動画の共有リンクがオンの場合のみ含まれます。 |
スクリーンショットはファイルとしてスペースにアップロードされるため、Cleveraで記事を削除しても表示され続けます。記事にアップロードされた動画ファイルはCleveraへのリンクとして残り、一定期間で期限切れになります。再度公開して更新してください。
公開済みページを更新する
公開は一方向のみです。Cleveraで記事を編集してもGitBookページは更新されず、GitBookでの編集内容がCleveraに戻ることもありません。記事を編集した後は、同じスペースに再度公開してください。Cleveraは同じタイトル（大文字小文字は区別されません）または同じアドレスを持つページを探し、「この記事は既にGitBookに存在します。」と表示します。
- 既存の記事を更新すると、そのページの内容とタイトルが上書きされます。アドレスは変わりません。GitBookで行われた変更は上書きされますが、GitBookの履歴から復元可能です。GitBookで更新をクリックしてください。
- 新しい記事を作成すると、入力した新しいタイトル（Cleveraは「Set up billing (2)」などを提案します）で、独自のアドレスを持つ2つ目のページが追加されます。新しい記事を作成をクリックしてください。
接続解除とアクセス権の取り消し
- Cleveraで連携を開き、GitBookをクリックして接続解除を選択し、確定します。既に公開したページはGitBookに残ります。
- GitBookのDeveloperページでアクセスキーを削除し、再利用できないようにします。
トラブルシューティング
| 表示内容 | 対処方法 |
|---|---|
| 「先にキーを貼り付けてください。」 | キーフィールドが空です。 |
| 「GitBookアクセスキーが無効です。確認して再試行してください。」 | キーが間違っているか削除されています。新しく作成して貼り付けてください。 |
| 「GitBookアクセスキーの検証に失敗しました。」または「キーを確認できませんでした。再試行してください。」 | GitBookが応答しませんでした。少し待ってから再試行してください。 |
| 「少なくとも1つのサイトを選択してください。」 | 接続の前に少なくとも1つのサイトにチェックを入れてください。 |
| 「GitBookのスペースやドキュメントサイトが見つかりませんでした。自動作成もできませんでした。GitBookでスペースを作成してから再試行してください。」 | GitBookでスペースを作成し、再度接続してください。 |
| 「GitBookへの接続に失敗しました。アクセスキーを確認してください。」 | キーを確認し、再度接続してください。 |
| 「GitBookスペースを読み込めませんでした。再試行してください。」 | 再試行をクリックしてください。繰り返される場合はGitBookを再接続してください。 |
| 「公開先のスペースを選択してください。」 | 先にスペースを選択してください。 |
| リストにスペースがない | 選択したサイトに含まれていないか、キーのユーザーが閲覧権限を持っていません。再接続してサイトを選択してください。 |
| 「GitBookがページコンテンツを拒否しました」または「GitBookが変更リクエストをマージできませんでした」（GitBookの理由付き） | キーのユーザーがそのスペースを編集できないか、GitBookが変更を拒否しました。GitBookで権限を確認し、再試行をクリックしてください。 |
| 「アクセスキーが見つかりません。GitBookを再接続してください。」 | キーを使用してGitBookを再接続してください。 |
| 「記事コンテンツが空か無効です。」 | 記事にまだ内容がありません。開いて確認してから公開してください。 |
| 「置換対象のページがGitBookで見つかりませんでした。移動または削除された可能性があります。」 | 代わりに新しい記事を作成を選択してください。 |
| 「GitBookへの公開に失敗しました。再試行してください。」または「GitBookのページ更新に失敗しました。再試行してください。」 | 再試行をクリックしてください。失敗し続ける場合は、新しいキーで再接続してください。 |