Tutorial: author docs locally with dxb

In a working folder, run:

dxb init acme-docs --name "Acme Docs"
cd acme-docs

The CLI prints ✓ Initialized Acme Docs in /path/to/acme-docs and a list of next steps. If the folder already holds a Doxbrix project, it stops with This folder is already a Doxbrix docs project.; add --force only if you mean to re-scaffold.

The project contains:

acme-docs/
├── .doxbrix/
│   ├── config.json          # links this folder to a hosted project; never holds a token
│   └── documentation.json   # documentation brief used by dxb docs commands
├── docs.json                # the manifest: spaces and navigation
├── introduction.mdx
└── guides/
    └── quickstart.mdx

The manifest, docs.json, defines the project's spaces (top-level sections, each with its own navigation) and the pages and groups (navigation folders) inside them:

{
  "version": 1,
  "spaces": [
    {
      "name": "Documentation",
      "slug": "docs",
      "nav": [
        { "type": "page", "file": "introduction" },
        {
          "type": "group",
          "label": "Guides",
          "items": [{ "type": "page", "file": "guides/quickstart" }]
        }
      ]
    }
  ]
}

Page file values are paths without the .mdx extension. For every field, see docs.json and page format reference.

To keep docs in a subfolder of an existing repository, run dxb init . --base-path docs instead.

Run:

dxb dev --open

The CLI prints ✓ dxb dev running at http://localhost:4000 and opens your browser. The preview reloads automatically when you save a file. It approximates the hosted site; the live site stays authoritative.

Leave this terminal running and open a second terminal in acme-docs for the next steps. If port 4000 is busy, the CLI prints Port 4000 is already in use.; run dxb dev --port 5000 instead. Press Ctrl-C to stop the server.

The scaffolded pages are intentionally marked unfinished with the line <!-- doxbrix:starter-page -->. Open introduction.mdx and replace its whole content with a real page, for example:

---
title: "Acme Docs"
description: "Learn how to install Acme and send your first request."
---

# Acme Docs

Acme is an HTTP service that stores and serves product catalog data.
Use these guides to install Acme and send your first request.

- [Quickstart](/guides/quickstart): run Acme locally in five minutes.

Do the same for guides/quickstart.mdx. Save both files; the browser preview updates.

Each page starts with frontmatter, the block between --- lines. title and description are used for navigation, search and link previews.

Scaffold a new page and add it to navigation in one command:

dxb new page guides/authentication --title "Authentication"

The CLI prints ✓ Created guides/authentication.mdx and Added to docs.json. The page is appended to the first space's navigation; use --space <slug> to target another space. Open the file and replace Start writing here. and the starter marker with your content.

If you create files by hand instead, run dxb sync to fold new files and folders into docs.json. Run dxb sync --dry-run first to see what it would change.

Run:

dxb lint

dxb lint validates the manifest, frontmatter, links, images and components. Each finding prints as error <rule>: <message> or warn <rule>: <message>. A page that still holds starter content fails with:

✗ error starter-page: 'guides/authentication.mdx' still contains starter content; replace it with researched reader-ready documentation.

Fix every error and run dxb lint again until it prints ✓ No problems found. Errors matter because dxb push refuses to upload a project with lint errors. Add --strict to treat warnings as failures too.

If you haven't signed in on this computer, run:

dxb login

Approve the request in the browser. The CLI prints ✓ Logged in as you@example.com (profile: default). For details, see Install the dxb CLI and sign in.

Create a Doxbrix project and link this folder to it:

dxb link --create --name "Acme Docs" --visibility public

The CLI prints ✓ Linked to acme-docs (Acme Docs). and next: dxb push. It writes the project ID into .doxbrix/config.json, which is safe to commit.

To link to a project that already exists, pass its slug or ID instead: dxb link acme-docs. To set up Git sync at the same time, add --git-repo owner/name and a connected Git account; see Sync a project with a Git repository.

Run a dry run to see what would change without writing anything:

dxb push --dry-run

The CLI prints a summary such as ✓ Would push 3 page(s): 3 created, 0 updated, 1 space(s). If any file isn't listed in docs.json, it warns that those files will not be published and suggests dxb sync.

Upload the pages as drafts:

dxb push

The CLI prints ✓ Pushed 3 page(s): 3 created, 0 updated, 1 space(s). and Uploaded as drafts. Run 'dxb push --publish' when ready. Doxbrix converts each MDX page into editor blocks, so teammates can review the drafts in the browser. See Submit, review and approve pages.

When the drafts are ready, publish them:

dxb push --publish

Confirm the Publish 3 page(s) to 'acme-docs'? [y/N] prompt with y. The CLI prints Published pages, search, and AI are updated.