Orbit
Anzeigen Ihrer Projekt-README in Orbit
The Docs tab renders your repository's README inside KPanel, so the project's own documentation is one click from its deployments instead of in a browser tab someone has to go and find.
Die Registerkarte "Docs" rendert die README deines Repositorys in KPanel, sodass die projektinterne Dokumentation nur einen Klick von den Bereitstellungen entfernt ist, statt in einem Browser-Tab zu sein, den jemand erst noch suchen muss.
Wo sich die Registerkarte "Docs" befindet
Öffne Orbit, klicke auf das Projekt und wähle Docs unter der Gruppe Overview in der Projekttab-Leiste.
Es gibt nichts zu konfigurieren. Wenn das Projekt ein verbundenes Repository mit einer README im Root-Verzeichnis hat, rendert die Registerkarte diese.
Welche Datei wird angezeigt
Orbit ruft die README aus dem Standard-Branch des verbundenen Repositorys ab.
Auf GitHub versucht es mehrere herkömmliche Namen nacheinander: README.md, readme.md, README.MD, README und readme.txt und nimmt die erste, die existiert. Auf GitLab und Bitbucket wird nach README.md gesucht.
Es wird nur das Root-Verzeichnis des Repositorys überprüft. Eine README in einem Unterverzeichnis, einschließlich des Root-Verzeichnisses einer Monorepo-App, wird nicht erfasst.
Der Inhalt wird etwa fünf Minuten lang zwischengespeichert. Wenn du eine Änderung an deiner README veröffentlichst, zeigt die Registerkarte den alten Text noch kurzzeitig an. Das ist normal; warte und lade die Seite erneut, statt anzunehmen, dass die Änderung nicht übernommen wurde.
Was wird gerendert
Die README wird als Markdown gerendert: Überschriften, Listen, Tabellen, Links, Inline-Code und Fenced-Code-Blöcke werden alle wie erwartet angezeigt.
Relative Bildpfade in einer README verweisen auf das Repository, nicht auf KPanel, sodass Bilder, die auf der Website deines Anbieters funktionieren, hier möglicherweise nicht aufgelöst werden. Wenn ein Bild wichtig ist, verwende eine absolute URL.
Leere Zustände
Zwei Zustände ersetzen den Inhalt, wenn es nichts zu zeigen gibt:
- Kein Repository verbunden, mit einer Schaltfläche Repository verbinden. Verbinde zuerst eines: siehe GitHub-Repository verbinden, GitLab-Repository verbinden oder Bitbucket-Repository verbinden.
- Keine README gefunden, mit der Aufforderung, eine
README.mdzum Root-Verzeichnis deines Repositorys hinzuzufügen, mit einem Link zu deren Erstellung bei deinem Anbieter.
Beide verlinken zum Anbieter, sodass du sofort handeln kannst, und die ausgefüllte Ansicht hat einen Link Anzeigen auf, um zur Datei selbst zu gelangen, wenn du sie bearbeiten möchtest.
Eine README schreiben, die es wert ist, gerendert zu werden
Da diese Registerkarte neben dem Bereitstellungsverlauf sitzt, ist die nützlichste README für ein Orbit-Projekt eine operative. Jemand öffnet sie, weil er das Projekt gerade erhalten hat und etwas sicher ändern muss.
Eine funktionierende Struktur:
Was das ist. Ein Absatz. Was das Projekt tut und wem es dient.
Lokale Ausführung. Die genauen Befehle, einschließlich des Paketmanagers. pnpm install && pnpm dev ist besser als ein Absatz, der dasselbe beschreibt.
Umgebungsvariablen. Welche existieren und wofür jede verwendet wird. Niemals die Werte: Diese gehören in die Umgebungsvariablen des Projekts, nicht in eine Datei im Repository. Siehe Umgebungsvariablen in Orbit.
Wie es bereitgestellt wird. Welcher Branch ist Produktion, ob Tags bereitgestellt werden und welche Gates gelten. Verweise auf die Registerkarte Orbit Deployment Pipeline, anstatt sie zu duplizieren, da die Registerkarte nicht veralten kann, deine README aber schon.
Wie man ein Rollback durchführt. Zwei Sätze und ein Link zu Rollback einer Bereitstellung. Das ist das, was Menschen in ihrem schlimmsten Moment brauchen, und es gehört dorthin, wo sie danach suchen.
Wem gehört es. Ein Team oder eine Person. Projekte überdauern die Menschen, die sie eingerichtet haben.
Gib niemals Anmeldedaten in eine README ein. Eine Verbindungszeichenfolge, ein API-Schlüssel oder ein Passwort, das sich im Repository befindet, ist permanent in der Historie, und das Löschen in einem späteren Commit entfernt es nicht. Wenn das passiert ist, erneuere die Anmeldedaten, anstatt zu versuchen, die Historie zu bereinigen.
Hinzufügen eines Live-Status-Badges
Da die README hier und bei deinem Anbieter gerendert wird, lohnt es sich, ein Bereitschaftsstatus-Badge hinzuzufügen. Orbit veröffentlicht eines für jedes Projekt.
Öffne Settings und suche die Karte Status badge. Sie zeigt eine Live-Vorschau und drei Schaltflächen zum Kopieren: die Badge-URL, ein Markdown-Snippet und ein HTML-Snippet. Füge das Markdown oben in deine README ein.
Das Badge ist ein kleines SVG, das den aktuellen Status der Produktionsumgebung des Projekts anzeigt: deployed, building, failed, queued oder no deployments. Es benötigt keine Authentifizierung, sodass es für jeden, der das Repository liest, gerendert wird, und es verlinkt zurück zum Projekt in KPanel.
Das ergibt dir eine README, die auf einen Blick zeigt, ob die Produktion aktuell gesund ist. Es ist die einzelne wertvollste Zeile, die du hinzufügen kannst.
Es ehrlich halten
Eine README, die ein Setup beschreibt, das das Projekt nicht mehr hat, ist schlimmer als gar keine README, weil Menschen darauf vertrauen. Zwei Gewohnheiten halten sie genau:
- Verlinken statt duplizieren. Alles, das in KPanel sichtbar ist, wie Build-Einstellungen, Gates und Umgebungskonfiguration, sollte verlinkt werden, nicht wiederholt.
- Aktualisiere es im selben Pull Request. Wenn eine Änderung die Art beeinflusst, wie das Projekt läuft, gehört die README-Änderung in diesen Pull Request, nicht in eine Aufräumarbeit später.
Fehlerbehebung
Die Registerkarte zeigt eine alte Version. Der fünfminütige Cache. Warte und lade erneut.
Keine README gefunden, aber es gibt eine. Überprüfe, ob sie im Repository-Root liegt und README.md heißt. Auf GitLab und Bitbucket muss der Name exakt übereinstimmen.
Das Repository ist verbunden, aber die Registerkarte sagt, dass es nicht ist. Die Verbindung könnte den Zugriff verloren haben, z.B. wenn die Integration auf der Anbieterseite entfernt wurde. Stelle sie aus den Projekteinstellungen erneut her.
Bilder laden nicht. Relative Pfade werden hier nicht aufgelöst. Verwende absolute URLs.
Das Badge zeigt keine Bereitstellungen. Die Produktionsumgebung hatte noch nie eine erfolgreiche Bereitstellung. Stelle einmal bereit und es wird aktualisiert.
Wo du als nächstes hingehen solltest
- Orbit Deployment Pipeline, die Live-Version dessen, was eine README normalerweise zu beschreiben versucht.
- Orbit Project Settings für das Status-Badge und den Rest der Konfiguration.
- Umgebungsvariablen in Orbit für die Werte, die eine README niemals enthalten darf.