Uw projectleesmij bekijken 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.

De tab Docs rendert de README van je repository in KPanel, zodat de projectdocumentatie slechts één klik verwijderd is van de deployments in plaats van in een browsertabblad dat iemand moet gaan zoeken.

Waar de Docs Tab Zich Bevindt

Open Orbit, klik op het project en kies Docs onder de groep Overview in de projecttabbladstrip.

Er is niets in te stellen. Als het project een verbonden repository heeft met een README in de root, rendert de tab deze.

Welk Bestand Wordt Weergegeven

Orbit haalt de README op van de standaardbranch van de verbonden repository.

Op GitHub probeert het verschillende gebruikelijke namen achtereenvolgens: README.md, readme.md, README.MD, README, en readme.txt, en gebruikt de eerste die bestaat. Op GitLab en Bitbucket zoekt het naar README.md.

Alleen de root van de repository wordt gecontroleerd. Een README in een subdirectory, inclusief de rootdirectory van een monorepo-app, wordt niet opgehaald.

De inhoud wordt ongeveer vijf minuten in cache opgeslagen. Push een wijziging naar je README en het tabblad zal nog even de oude tekst tonen. Dit is normaal; wacht en herlaad in plaats van aan te nemen dat de wijziging niet is doorgevoerd.

Wat Rendert

De README wordt als markdown gerenderd: koppen, lijsten, tabellen, koppelingen, inline code en fenced code blocks worden allemaal weergegeven zoals je zou verwachten.

Relatieve afbeeldingspaden in een README wijzen naar de repository, niet naar KPanel, dus afbeeldingen die op de site van je provider werken, kunnen hier mogelijk niet worden opgelost. Als een afbeelding belangrijk is, gebruik dan een absolute URL.

Lege Staten

Twee staten vervangen de inhoud wanneer er niets te tonen is:

Geen repository verbonden, met een knop Connect repository. Verbind er eerst een: zie Connecting a GitHub Repository, Connecting a GitLab Repository of Connecting a Bitbucket Repository.
No README found, waarin je wordt gevraagd een README.md aan de root van je repository toe te voegen, met een link om er een aan te maken op je provider.

Beide verwijzen naar de provider zodat je onmiddellijk actie kunt ondernemen, en de ingevulde weergave bevat een View on link naar het bestand zelf voor als je het wilt bewerken.

Een README Schrijven Die Het Waard Is om Gerend Te Worden

Omdat dit tabblad naast de implementatiehistorie staat, is de meest bruikbare README voor een Orbit-project er een met operationele informatie. Iemand opent het omdat ze net het project hebben gekregen en iets veilig moeten veranderen.

Een structuur die werkt:

Wat dit is. Één alinea. Wat het project doet en wie het dient.

Lokaal uitvoeren. De exacte opdrachten, inclusief de packagemanager. pnpm install && pnpm dev is beter dan een alinea die hetzelfde beschrijft.

Omgevingsvariabelen. Welke bestaan en waar elk voor is. Nooit de waarden: die horen thuis in de omgevingsvariabelen van het project, niet in een bestand in de repository. Zie Environment Variables in Orbit.

Hoe het implementeert. Welke branch is production, of tags implementeren en welke gates van kracht zijn. Wijs naar het tabblad Orbit Deployment Pipeline in plaats van het te dupliceren, omdat het tabblad niet verouderd kan raken en je README wel.

Hoe je terug kunt rollen. Twee zinnen en een link naar Rolling Back a Deployment. Dit is het ding dat mensen op hun slechtste moment nodig hebben, en het hoort waar ze zullen zoeken.

Wie bezit het. Een team of een persoon. Projecten overleven de mensen die ze hebben opgezet.

Zet nooit inloggegevens in een README. Een verbindingsstring, een API-sleutel of een wachtwoord dat in een repository is gecommit, blijft permanent in de geschiedenis, en het verwijderen ervan in een latere commit verwijdert het niet. Als het is gebeurd, draai de inloggegevens door in plaats van de geschiedenis te proberen schoon te maken.

Een Live Status Badge Toevoegen

Omdat de README hier en op je provider wordt weergegeven, is een deploy status badge het waard om toe te voegen. Orbit publiceert er een voor elk project.

Open Settings en zoek de kaart Status badge. Het toont een live preview en drie kopieerknoppen: de badge URL, een markdown fragment en een HTML fragment. Plak de markdown boven aan je README.

De badge is een kleine SVG die de huidige status van de productieomgeving van het project rapporteert: deployed, building, failed, queued, of no deployments. Het vereist geen authenticatie, dus het rendert voor iedereen die de repository leest, en het linkt terug naar het project in KPanel.

Dat geeft je een README die in één oogopslag toont of production momenteel gezond is. Het is de enige regel met de hoogste waarde die je eraan kunt toevoegen.

Het Eerlijk Houden

Een README die een setup beschrijft die het project niet meer heeft, is erger dan geen README, omdat mensen erop vertrouwen. Twee gewoonten houden het nauwkeurig:

Link in plaats van te dupliceren. Alles wat zichtbaar is in KPanel, zoals build-instellingen, gates en omgevingsconfiguratie, moet worden gekoppeld, niet herhaald.
Update het in dezelfde pull request. Als een wijziging de manier waarop het project draait verandert, hoort de README-wijziging in die pull request, niet in een opruiming later.

Probleemoplossing

Het tabblad toont een oude versie. De cache van vijf minuten. Wacht en herlaad.

Geen README gevonden, maar er is er een. Controleer of deze in de repository root staat en de naam README.md heeft. Op GitLab en Bitbucket moet de naam exact overeenkomen.

De repository is verbonden maar het tabblad zegt dat het niet is. De verbinding kan toegang hebben verloren, bijvoorbeeld als de integratie aan de providerzijde is verwijderd. Verbind het opnieuw via de projectinstellingen.

Afbeeldingen laden niet. Relatieve paden worden hier niet opgelost. Gebruik absolute URLs.

De badge toont geen implementaties. De productieomgeving heeft nog nooit een succesvolle implementatie gehad. Implementeer eenmaal en deze wordt bijgewerkt.

Waar Je Vervolgens Naartoe Gaat

Orbit Deployment Pipeline, de live versie van wat een README meestal probeert te beschrijven.
Orbit Project Settings voor de status badge en de rest van de configuratie.
Environment Variables in Orbit voor de waarden die een README nooit mag bevatten.