How It Works

The short version

Doxa turns a GitHub repository into a published docs site in four stages:

1. Doxabot reads the repository you connected to a project.

2. Doxabot writes MDX pages from what it finds.

3. Doxa stores the output as a versioned docs artifact.

4. Publishing makes one version the active version, and the shared renderer serves it at <slug>.doxa.page or your custom domain.

Each stage is covered below, followed by the parts you control after the first generation.

Doxabot reads your repository

Doxabot is the generation agent. It works on one project at a time. To read your code, Doxa needs access to the repository through the Doxa GitHub App. You choose the repository on the new-project screen, and each generation checks out that repository's current contents to read.

Doxabot uses the repository as its source of truth. Pages describe what the code, configuration, and existing docs say. If you want Doxabot to emphasize certain topics, audiences, or terminology, add project instructions on the Generations page. See Generations and Doxabot Instructions.

Doxabot writes MDX pages

Doxabot writes each page as MDX, a Markdown file that can include Doxa components such as Card, Note, Step, and Tabs. The result is a set of pages with navigation, which you can then edit.

Pages you edit in the dashboard are plain MDX too. You can switch between a rich-text view and the MDX source at any time. See Editing Pages in the Content Editor.

Generated output is stored as versioned artifacts

Each generation produces a new docs artifact. An artifact is a complete, versioned snapshot of the site: its pages, navigation, and assets. Storing the output as a versioned artifact means:

• A generation never overwrites the live site while it runs.

• Earlier versions remain available, so a previous publication can be restored.

• Each generation's result can be reviewed before it goes live.

Generations are tracked on the Generations page, which shows progress, history, and the result of each run.

Publishing switches the active version

Publishing does not copy files to a new location. It changes which version is active for the project. When you publish a branch, Doxa marks that branch's version as the active one, and the renderer begins serving it. Restoring a previous publication works the same way in reverse: the older version becomes active again.

Docs live on branches while you work. A branch holds working changes, so readers keep seeing the active version until you publish. See Branches, Previews, Publishing, and Restore for the full flow.

How the shared renderer serves a site

Published sites are rendered by one shared docs renderer. It does not store a separate copy of each site. When a reader opens a page, the renderer:

1. Identifies the project from the requested domain.

2. Loads the active version's pages, navigation, and settings.

3. Renders the page with the MDX components, math, syntax highlighting, search, and API reference support.

Because every site uses the same renderer, a new renderer release improves every site without regenerating its content. Your site's appearance and navigation come from its site settings, not from the renderer itself. See Appearance and Navigation.

Each site also gets AI-friendly routes, /llms.txt and /llms-full.txt, that describe the published content to AI tools.

Where each site lives

Preview links show a branch before it is published. Preview links are not the live site, so readers see the change only after you publish.

What you control after generation

Generation creates the first version. After that, you decide what goes live:

• Edit pages in the content editor, or let an agent write them through MCP.

• Work on branches so changes are isolated until you publish.

• Publish and restore from publication history.

• Configure the site with Site settings, including navigation, SEO, features, and domains.

Next steps