ReadMeへの記事公開
ReadMeプロジェクトをAPIキーで接続し、Cleveraの記事を選択したカテゴリのガイドとして公開します。その際、スクリーンショットもReadMeにアップロードされます。コールアウト、ステップ、動画の変換方法、更新の仕組み、および一般的なエラーについて説明します。
Cleveraの記事をReadMeプロジェクトのガイドとして、選択したガイドカテゴリに公開します。スクリーンショットはReadMeにアップロードされます。
始める前に
- Clevera: ワークスペースがProまたはカスタムプランであること。また、ReadMeを接続するにはオーナーまたは管理者の権限が必要です。接続後は、記事を編集できるユーザーであれば誰でも公開できます。他のツールへの記事公開を参照してください。
- ReadMe: 管理可能なプロジェクトがあり、ガイドセクションに少なくとも1つのカテゴリがあること。1つのキーで1つのプロジェクトを接続します。
- 現在のReadMeプロジェクト: Cleveraは、ReadMe Refactored上のプロジェクトで提供されるReadMeの現行（v2）APIを通じて公開します。古いプラットフォーム上のプロジェクトは接続できません。
- バージョン: Cleveraは、プロジェクトのメイン（安定版）バージョンのガイドに公開します。
- 記事: まず記事を作成してください。公開時には記事のみが送信されます。動画を含める場合は、記事内に配置してください。記事で動画を表示するを参照してください。
ReadMe APIキーを見つける
ReadMeプロジェクトで、Configuration → API Keysを開き、キーをコピーします（リストが空の場合は作成してください）。このキーはプロジェクトへのフルアクセス権を与えるため、非公開にしてください。
ReadMeを接続する
接続ウィンドウを開く
Cleveraで、サイドバーのワークスペース名をクリックし、連携を選択します。ReadMeを見つけて接続をクリックします。ReadMeを接続ウィンドウに「キーを貼り付けてください。保存前に確認を行います。」と表示されます。
キーを貼り付けて確認する
APIキーにキーを貼り付け、キーを確認をクリックします。ReadMeで承認されると「キーが承認されました。」と表示され、公開先サイトにプロジェクトが表示されます。
接続
接続をクリックします。「ReadMeが接続されました。」と表示され、接続済みの下にプロジェクト名が表示されます。
キーはClevera側では期限切れになりません。別のプロジェクトを接続するには、ReadMe接続の再接続を使用し、そのプロジェクトのキーを貼り付けてください。古いキーが置き換わります。
ReadMeに記事を公開する
「公開」タブを開く
エディタで、共有 → 公開をクリックし、公開の準備ができましたの下にあるReadMeタイルをクリックします。
ガイドカテゴリを選択する
公開先のプロジェクトに接続中のプロジェクトが表示されます。ガイドカテゴリを選択してください。「記事はこのカテゴリのガイドセクションに配置されます。」「ガイドカテゴリがまだありません」と表示される場合は、先にReadMeで作成してください。
公開
ReadMeに公開をクリックします。Cleveraはまず既存のコピーを探します。同じアドレスのガイドが既に存在する場合は、対処方法を選択してください（ガイドを更新するを参照）。完了すると「ReadMeに公開されました。」と表示されます。ReadMeで開くをクリックしてガイドを確認してください。
処理中に共有ウィンドウを閉じても問題ありません。完了すると通知が届きます。
ガイドのアドレスはタイトルから生成されます。「Set up billing」はドキュメントサイト上で /docs/set-up-billing となります。他の言語やアクセント記号付きのタイトルは、まずラテン文字に変換されます。アドレスが既に使用されている場合、ReadMeは新しいガイドに少し異なるアドレスを割り当てます。
ReadMeでのガイドの表示
ガイドのタイトルは記事のタイトルと同じになります。ガイドには記事の内容のみが含まれ、記事の元となった動画は追加されません。
| Cleveraでの表示 | ReadMeでの表示 |
|---|---|
| 見出し、段落 | 見出しとテキスト |
| 太字、斜体、取り消し線、インラインコード、リンク | 保持されます。他のCleveraページへのリンクはテキストのみ保持されます。 |
| ハイライト、上付き文字、下付き文字 | 保持されます |
| 箇条書き、番号付きリスト、チェックリスト | リストとチェックリスト |
| 引用 | 引用 |
| コードブロック | 言語とコードタイトル付きのコードブロック |
| 区切り線 | 区切り線 |
| テーブル | 各セルのテキストを含むテーブル |
| コールアウト | ReadMeのコールアウト（タイトル付き）：📘（情報・メモ）、👍（ヒント・成功）、🚧（警告）、❗️（危険） |
| 番号付きステップ | 番号付きリスト：各ステップのタイトルは太字になり、コンテンツはその下にネストされます |
| タブ | 各タブのラベルは太字になり、その後にコンテンツが続きます。コードのみを含むタブはReadMeのコードタブになります。 |
| 折りたたみセクション | 展開可能なセクション |
| カード | 説明付きのリンクリスト。カードアイコンは除外されます |
| 数式 | コード |
| スクリーンショット | ReadMeにアップロードされた画像。キャプションは斜体になります |
| 記事内の動画と埋め込み | ReadMeの埋め込み。Cleveraの動画は、その動画の共有リンクが有効な場合のみ含まれます。 |
テキスト内の波括弧と山括弧はエスケープされるため、ReadMeのページ形式でそのまま表示されます。
スクリーンショットはReadMeにアップロードされるため、Cleveraで記事を削除しても表示され続けます。アップロードに失敗したスクリーンショットや記事内の動画ファイルは、一定時間で期限切れになるCleveraへのリンクとして残ります。再度公開して更新してください。
ガイドを更新する
公開は一方向のみです。Cleveraで記事を編集してもガイドは更新されず、ReadMeでの編集内容がCleveraに反映されることもありません。記事を編集した後は、再度公開してください。
Cleveraはガイドセクション全体から同じアドレスのガイドを探し、「この記事は既にReadMeに存在します。」と表示します。表示をクリックして開いた後、以下を選択してください：
- 既存の記事を更新：そのガイドを上書きします（アドレスは同じで、タイトルとコンテンツが新しくなります）。ReadMeで更新をクリックします。
- 新しい記事を作成：入力した新しいタイトルで、独自のアドレスを持つ新しいガイドを作成します。新しい記事を作成をクリックします。
Cleveraでガイドを更新すると、前回の公開以降にReadMeで行われた変更は上書きされます。
接続解除とアクセス権の取り消し
- Cleveraで連携を開き、ReadMeをクリックして接続解除を選択し、確定します。既に公開済みのガイドはReadMeに残ります。
- ReadMeでConfiguration → API Keysを開き、Cleveraに提供したキーを削除します。
トラブルシューティング
| 表示されるメッセージ | 対処方法 |
|---|---|
| 「先にキーを貼り付けてください。」 | キーフィールドが空です。 |
| 「無効なAPIキーです。ReadMe APIキーを確認してください。」 | キーが間違っているか、削除されています。Configuration → API Keysから再度コピーしてください。 |
| 「ReadMeからプロジェクト情報を取得できませんでした。」または「キーを確認できませんでした。再試行してください。」 | ReadMeが応答していないか、プロジェクトがReadMe Refactored上にありません（Cleveraには必須です）。再試行するか、新しいキーを試してください。プロジェクトがReadMeの古いプラットフォーム上にある場合は接続できません。 |
| 「APIキーを検証できませんでした。ReadMe APIキーを確認してください。」または「ReadMeに接続できませんでした。APIキーを確認してください。」 | キーを確認して再度接続してください。 |
| 「ガイドカテゴリがまだありません」 / 「公開するにはReadMeでガイドカテゴリを作成してください。」 | ReadMeのガイドにカテゴリを追加してから、公開タブを再度開いてください。 |
| 「先にカテゴリを選択してください。」または「このガイドを公開するReadMeカテゴリを選択してください。」 | 公開前にガイドカテゴリを選択してください。 |
| 「このアイテムを表示することはできますが、公開することはできません。編集権限を持つユーザーに依頼してください。」 | 公開するには記事への編集権限が必要です。 |
| 「APIキーが見つかりません。ReadMeを再接続してください。」 | キーを使用してReadMeを再度接続してください。 |
| 「記事のコンテンツが空か無効です。」 | 記事にコンテンツがありません。開いて確認してから公開してください。 |
| 「ReadMeに公開できませんでした」とReadMeからのメッセージ（スラッグやカテゴリに関するものなど） | ReadMeがガイドを拒否しました。カテゴリが存在するか確認するか、記事名を変更して再試行をクリックしてください。 |
| 「ReadMeのガイドを更新できませんでした」 | 更新しようとしたガイドがReadMeで削除または名前変更されています。再度公開し、新しい記事を作成を選択してください。 |
| 「ReadMeに公開できませんでした。再試行してください。」 | 再試行をクリックしてください。それでも失敗する場合は、新しいキーで再度接続してください。 |