OrbitでプロジェクトREADMEを表示する

Docs タブはリポジトリの README を KPanel 内にレンダリングするため、プロジェクト自体のドキュメントは、誰かが探して別のブラウザ タブで開く代わりに、デプロイメントから 1 クリックの距離にあります。

Docs タブの場所

Orbit を開き、プロジェクトをクリックして、プロジェクト タブ ストリップの Overview グループの下から Docs を選択します。

設定は何もありません。プロジェクトに接続されたリポジトリがあり、ルートに README がある場合、タブはそれをレンダリングします。

表示されるファイル

Orbit は接続されたリポジトリのデフォルト ブランチから README をフェッチします。

GitHub では複数の従来の名前を順番に試します: README.md、readme.md、README.MD、README、readme.txt の中で、最初に存在するものを採用します。GitLab と Bitbucket では README.md を探します。

チェックされるのはリポジトリのルートだけです。サブディレクトリ内の README (モノレポ アプリのルート ディレクトリを含む) は検出されません。

レンダリングされる内容

README はマークダウンとしてレンダリングされます: 見出し、リスト、テーブル、リンク、インライン コード、フェンスで囲まれたコード ブロックはすべて期待通りに表示されます。

README 内の相対画像パスは KPanel ではなくリポジトリを指しているため、プロバイダー自体のサイトで機能する画像がここで解決されないことがあります。画像が重要な場合は、絶対 URL を使用してください。

空の状態

コンテンツがない場合、2 つの状態がコンテンツに代わります:

• リポジトリが接続されていません: Connect repository ボタンが表示されます。まず接続してください: GitHub リポジトリを接続する、GitLab リポジトリを接続する、または Bitbucket リポジトリを接続するを参照してください。
• README が見つかりません: リポジトリのルートに README.md を追加するよう促し、プロバイダーで作成するリンクが表示されます。

どちらもプロバイダーへのリンクがあるため、すぐに対応でき、内容が表示されたビューには編集時に使用できるファイル自体の View on リンクがあります。

レンダリングする価値のある README の作成

このタブはデプロイ履歴の隣にあるため、Orbit プロジェクトに最も役立つ README は運用上のものです。誰かがプロジェクトを引き継ぎ、安全に何かを変更する必要がある場合に開くものです。

機能する構造:

これは何か。 1 段落。プロジェクトが何をするのか、誰に向けたものなのか。

ローカルで実行する。 パッケージ マネージャーを含む正確なコマンド。pnpm install && pnpm dev は同じことを説明する段落より優れています。

環境変数。 存在する変数と各変数の用途。値は決して含めないでください: 値はリポジトリのファイルではなくプロジェクトの環境変数に属します。Orbit の環境変数を参照してください。

デプロイ方法。 どのブランチが本番環境か、タグがデプロイされるかどうか、どのゲートが有効か。README で複製する代わりに Orbit デプロイメント パイプライン タブを参照してください。タブは古くならず、README は古くなる可能性があるためです。

ロールバック方法。 2 文と デプロイメントのロールバック へのリンク。これは人々が最悪の状況にある時に必要なことであり、彼らが見るだろう場所に属するべきです。

所有者は誰か。 チームか個人。プロジェクトはそれを立ち上げた人よりも長く続きます。

ライブ ステータス バッジの追加

README はこことプロバイダーでレンダリングされるため、デプロイ ステータス バッジを追加する価値があります。Orbit はすべてのプロジェクトに対して公開しています。

Settings を開き、Status badge カードを見つけます。ライブ プレビューと 3 つのコピー ボタンが表示されます: バッジ URL、マークダウン スニペット、HTML スニペット。マークダウンを README の上部に貼り付けます。

バッジは、プロジェクトの本番環境の現在のステータスを報告する小さな SVG です: deployed、building、failed、queued、または no deployments。認証が不要なため、リポジトリを読む誰もがレンダリングでき、KPanel のプロジェクトにリンク バックします。

これにより、本番環境が現在健全かどうかを一目で示す README が得られます。これはそれに追加できる単一の最高値の行です。

正確性を保つ

プロジェクトが持たなくなったセットアップを説明する README は、人々がそれを信頼するため、README がない場合よりも悪いです。2 つの習慣がそれを正確に保ちます:

• 複製するのではなくリンクする。 ビルド設定、ゲート、環境設定など、KPanel に表示されるすべてのものは、再記載するのではなくリンクされるべきです。
• 同じプル リクエストで更新する。 変更がプロジェクトの実行方法を変更する場合、README の変更はそのプル リクエストに属し、後で整理するのではありません。

トラブルシューティング

タブに古いバージョンが表示される。 5 分間のキャッシュです。待機してからリロードしてください。

README が見つかりませんと表示されるが、README がある。 リポジトリ ルートにあり、README.md という名前が付いていることを確認してください。GitLab と Bitbucket では名前が完全に一致する必要があります。

リポジトリは接続されているのに、タブは接続されていないと表示される。 接続はアクセスを失った可能性があります。たとえば、プロバイダー側で統合が削除された場合です。プロジェクト設定から再度接続してください。

画像が読み込まれない。 相対パスはここで解決されません。絶対 URL を使用してください。

バッジに デプロイメントなし と表示される。 本番環境は成功したデプロイメントを 1 度も実施していません。1 回デプロイすると更新されます。

次に進む場所

• Orbit デプロイメント パイプライン: README が通常説明しようとする内容のライブ バージョン。
• Orbit プロジェクト設定: ステータス バッジとその他の設定用。
• Orbit の環境変数: README に含まれてはならない値用。