Set up a docs-as-code workflow

This guide sets you up to write documentation the way you write code: as files in your editor, versioned in Git, validated locally, and published with the `dxb`...

DUpdated July 10, 2026 2 min read Knowledge Management Team

In this article

This guide sets you up to write documentation the way you write code: as files in your editor, versioned in Git, validated locally, and published with the `dxb`...

Who this is for

Prerequisites

Step 1 — Install and authenticate

Step 2 — Initialize a project

This guide sets you up to write documentation the way you write code: as files in your editor, versioned in Git, validated locally, and published with the dxb CLI. By the end you'll have a working local docs project, a preview loop, and a publish command.

Who this is for

Developers and technical writers who prefer working in their editor and Git over a visual app, or teams that want documentation to live alongside their code.

Prerequisites

Node.js 18+.
A Doxbrix project API token.
Basic familiarity with the terminal and Git.

Step 1 — Install and authenticate

Install the CLI

bash

    npm install -g @doxbrix/cli

Set your token

Create a token in Settings → Project → API Tokens, then expose it:

bash

    export DOXBRIX_TOKEN="<your-token>"

See Authentication.

Step 2 — Initialize a project

In a new directory (or your app's repo), scaffold a docs project:

bash

dxb init . --name "My Docs"

This creates docs/docs.json, a starter .mdx file, .doxbrix/config.json linking the folder to a cloud project, and a Claude authoring skill. To convert an existing tree from another tool, add --from mintlify (or gitbook). See Initialize a project.

Step 3 — Put it under version control

bash

git init
git add .
git commit -m "Initialize Doxbrix docs"

Commit .doxbrix/config.json so teammates are linked automatically after cloning — it holds no secrets.

Step 4 — Preview locally

bash

dxb dev --open

As you edit .mdx files, the preview updates. See Local preview.

Step 5 — Write content

Create pages from the CLI so files and navigation stay in sync:

bash

dxb new page get-started/quickstart --title "Quickstart"

Then edit docs/get-started/quickstart.mdx using Doxbrix blocks:

mdx

---
title: Quickstart
description: Create a project and publish your first page in minutes.
---

# Quickstart

<Steps>
  <Step title="Install the CLI">Run `npm install -g @doxbrix/cli`.</Step>
  <Step title="Initialize">Run `dxb init`.</Step>
</Steps>

<Tip>Run `dxb dev` to preview as you write.</Tip>

Step 6 — Validate

bash

dxb lint --strict

Fix any errors it reports. See Lint & validate.

Step 7 — Review and publish

See what will change

bash

    dxb status
    dxb diff

Publish

bash

    dxb push --publish

Your changes go live within seconds. See Push & status.

Step 8 — Stay in sync with the app

If teammates also edit in the visual editor, connect Git sync so their app edits commit back to your repo automatically — there's no dxb pull. dxb status shows whether your local files have diverged from the cloud.