Dashboard Workflows

Branches, Previews, Publishing, and Restore

Create branches, build previews, review diffs, publish changes, and restore earlier publications

How branches work

Doxa stores documentation work in branches. A branch holds your working changes to a project's pages, so you can edit docs without changing the live site. When a branch is ready, you publish it, and the published site serves that branch's content.

Writes to main are rejected through the MCP server. A connected agent must create a named branch, make its changes there, and publish that branch.

Note:

Writes to main are rejected when they come through MCP. Create a named branch first, then write to that branch.

Workflow overview

Create a named branch

Give the branch a name that describes the change, such as api-auth-docs. Agents create a branch with the create_branch tool.

Edit pages on the branch

Change pages in the content editor, using Write mode for rich text or Split mode for MDX source with a rendered preview. See Editing Pages in the Content Editor. Agents can use write_page and edit_docs on the same branch.

Build a preview

Build a preview of the branch to check how its pages render before publishing. Agents use the build_preview tool for this step.

Review the branch diff

Compare the branch with the published content and check the changed pages before you publish. Agents read the same information with get_branch_diff, and check branch state with get_branch_status.

Publish the branch

Publish the branch to make it the active version of the site. Then open the published site at <slug>.doxa.page, or at your custom domain, and confirm that the changes appear.

Branch and publishing tools for agents

A connected agent uses MCP tools for the same steps. The scopes granted to the agent limit which tools it can run. See MCP Scopes and Approval Requests before you grant access.

Task	MCP tools
List, create, and inspect branches	`list_branches`, `create_branch`, `get_branch_status`, `get_branch_diff`
Sync a branch and build a preview	`sync_branch`, `build_preview`
Remove a branch	`delete_branch`
Publish and review history	`publish_branch`, `list_publications`, `restore_publication`

For parameters and behavior of each group, see Branches and Publish and history.

Publication history and restore

Each publication is recorded in publication history. Use it to find an earlier publication and restore it when a published change needs to be undone.

Open the publication history for the project and choose the publication to return to.
Restore that publication to make it the active version of the site again.
Agents call list_publications to find a publication and restore_publication to restore it.

Note:

Consequential agent actions can require an approval request before they run. See Agent actions and approvals and MCP Scopes and Approval Requests.

Common tasks

Make a docs change without affecting the live site: create a named branch and edit only on that branch.
Check a change before it goes live: build a preview and review the branch diff.
Undo a published change: open publication history and restore the earlier publication.
Let an agent draft docs safely: connect the agent with only the scopes it needs, and have it write to a named branch.

Editing Pages in the Content Editor

Write and Split modes for changing page content.

Custom Domains

Attach a custom domain and confirm it serves your docs.

Publish and history tools

MCP tools for publishing branches and restoring publications.

Documentation Branching

How branches store working changes for a project.

PreviousEditing Pages in the Content Editor NextAgent actions and approvals