Current
Documentation Branching
Understanding how Doxa stores docs work in branches, publishes changes, and keeps main stable
How branches fit into a project
Doxa stores documentation work in branches. A branch holds your working changes until you publish them into main, the version that your live site serves. Edits never reach readers until a branch is published, so you can draft, preview, and review changes without affecting the published site.
main is the immutable version that is currently live. A branch starts from a base version and records only the changes you made. When you read a branch, Doxa shows the base version with those changes applied. Pages you did not touch are not copied into the branch.
Branch kinds
Doxa uses two kinds of branches.
| Kind | Use | Visible in the dashboard |
|---|---|---|
| Named | Independent work created from main or another named branch. | Yes |
| Hidden | Working changes made while the editor shows main. | No |
Each user and site can have one hidden branch. The first edit you make while the editor shows main creates it. Publishing or discarding the hidden branch removes it. To keep work separate and reviewable, create a named branch before you start a larger change.
Branch purposes
Every named branch has a purpose.
| Purpose | Meaning |
|---|---|
user | Work that you or a connected agent created. |
generation_review | The output of a production generation that is waiting for review. See Generation Reviews. |
generation_backup | The site that a reviewed generation replaced. |
Only user branches count toward your branch limit.
Naming rules
Branch names follow these rules:
Use lowercase letters, numbers, and single hyphens.
Use 1 to 40 characters.
Do not use the reserved names
main,head,hidden,preview, ordraft.
Examples of valid names are pricing-page-update and api-auth-rewrite.
Working changes
A branch records one change for each file it touches. A change is either an update or a deletion. Changes fall into these areas:
Pages: the MDX source of each page.
Site structure: the section and page order that drives the sidebar and navigation.
Site settings: the values in your site configuration.
Images: uploaded images. A branch refers to the upload rather than storing a copy of the image. Agents add images with
upload_asset. The branch diff lists images underassets.
If you edit a page back to the same content as the base version, Doxa drops that change from the branch. Branches therefore stay small and only show real differences.
Home page
The home page of a site is the page that opens at /. You set it in Site settings under Navigation, or from the page menu with Set as default page. If no home page is set, or the saved one no longer exists, the first page of the default section opens.
The setting stores the page path, not its position. Reordering pages does not change the home page.
Renaming or moving the home page updates the setting in the same save. Deleting it removes the setting.
The home page is part of the published version. It goes live on publish, and a rollback restores the previous home page.
Saving, previews, and publishing
Each save to a branch increases the branch revision. A preview records the revision it was built from, so you can tell whether a preview is current. Build a preview from your branch, review the branch diff, and then publish when the changes are ready.
Publishing merges the branch into main as one new version. The new version becomes the live site, and the previous version stays in publication history, which you can use to restore it. Publishing only writes the pages that changed. Pages that the branch did not touch keep their existing content.
Note:
A changed page that fails the MDX check blocks publishing with an mdx_invalid error. The error lists the pages that need fixing. Saves are not blocked, so you can keep a draft that is still invalid, but you must fix it before the branch can be published. This applies to named branches and to the hidden branch of main.
Working with branches through MCP
Connected agents work with branches through the Doxa MCP server. Agents can create branches, edit pages, build previews, read diffs, and publish. Writes to main are rejected through MCP, so an agent always works on a branch. See Branches for the branch tools and Publish and history for publishing and restore.
Related guides
Create branches, build previews, review diffs, publish, and restore.
Edit pages in Write or Split mode and save to a branch.
Connect an agent that works on branches through OAuth scopes.
Review generated pages before they replace your published site.