Viewing Your Project 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.

Where the Docs Tab Lives

Open Orbit, click the project, and choose Docs under the Overview group in the project tab strip.

There is nothing to configure. If the project has a connected repository with a README at its root, the tab renders it.

Which File Is Shown

Orbit fetches the README from the default branch of the connected repository.

On GitHub it tries several conventional names in turn: README.md, readme.md, README.MD, README, and readme.txt, taking the first that exists. On GitLab and Bitbucket it looks for README.md.

Only the root of the repository is checked. A README inside a subdirectory, including the root directory of a monorepo app, is not picked up.

The content is cached for about five minutes. Push a change to your README and the tab will still show the old text briefly. That is expected; wait and reload rather than assuming the change did not land.

What Renders

The README is rendered as markdown: headings, lists, tables, links, inline code and fenced code blocks all display as you would expect.

Relative image paths inside a README point at the repository, not at KPanel, so images that work on your provider's own site may not resolve here. If an image matters, use an absolute URL.

Empty States

Two states replace the content when there is nothing to show:

No repository connected, with a Connect repository button. Connect one first: see Connecting a GitHub Repository, Connecting a GitLab Repository or Connecting a Bitbucket Repository.
No README found, prompting you to add a README.md to the root of your repository, with a link to create one on your provider.

Both link out to the provider so you can act immediately, and the populated view carries a View on link to the file itself for when you want to edit it.

Writing a README Worth Rendering

Because this tab sits next to the deploy history, the most useful README for an Orbit project is an operational one. Someone opens it because they have just been handed the project and need to change something safely.

A structure that works:

What this is. One paragraph. What the project does and who it serves.

Running it locally. The exact commands, including the package manager. pnpm install && pnpm dev beats a paragraph describing the same thing.

Environment variables. Which ones exist and what each is for. Never the values: those belong in the project's environment variables, not in a file in the repository. See Environment Variables in Orbit.

How it deploys. Which branch is production, whether tags deploy, and which gates are in force. Point at the Orbit Deployment Pipeline tab rather than duplicating it, because the tab cannot go stale and your README can.

How to roll back. Two sentences and a link to Rolling Back a Deployment. This is the thing people need at their worst moment, and it belongs where they will look.

Who owns it. A team or a person. Projects outlive the people who set them up.

Never put credentials in a README. A connection string, an API key or a password committed to a repository is in the history permanently, and deleting it in a later commit does not remove it. If it has happened, rotate the credential rather than trying to scrub the history.

Adding a Live Status Badge

Since the README is rendered here and on your provider, a deploy status badge is worth adding. Orbit publishes one for every project.

Open Settings and find the Status badge card. It shows a live preview and three copy buttons: the badge URL, a markdown snippet, and an HTML snippet. Paste the markdown at the top of your README.

The badge is a small SVG that reports the current status of the project's production environment: deployed, building, failed, queued, or no deployments. It needs no authentication, so it renders for anyone reading the repository, and it links back to the project in KPanel.

That gives you a README that shows, at a glance, whether production is currently healthy. It is the single highest-value line you can add to it.

Keeping It Honest

A README that describes a setup the project no longer has is worse than no README, because people trust it. Two habits keep it accurate:

Link rather than duplicate. Anything that is visible in KPanel, such as build settings, gates and environment configuration, should be linked to, not restated.
Update it in the same pull request. If a change alters how the project runs, the README change belongs in that pull request, not in a tidy-up later.

Troubleshooting

The tab shows an old version. The five-minute cache. Wait and reload.

No README found, but there is one. Check it is at the repository root and named README.md. On GitLab and Bitbucket the name has to match exactly.

The repository is connected but the tab says it is not. The connection may have lost access, for example if the integration was removed on the provider side. Reconnect it from the project settings.

Images do not load. Relative paths do not resolve here. Use absolute URLs.

The badge shows no deployments. The production environment has never had a successful deployment. Deploy once and it updates.

Where To Go Next

Orbit Deployment Pipeline, the live version of what a README usually tries to describe.
Orbit Project Settings for the status badge and the rest of the configuration.
Environment Variables in Orbit for the values a README must never contain.