docs.json and page format reference

Use this page to look up the format of a local Doxbrix docs project: the docs.json manifest, the page files it references, the frontmatter each page carries, and the checks that dxb lint and dxb docs check run against them.

You work with this format when you author docs locally with the dxb CLI or keep a project in a Git repository with Git sync. Git sync reads and writes the same manifest shape.

Project layout

A local docs project has three kinds of files:

dxb init creates this layout. dxb link writes .doxbrix/config.json.

my-docs/
├── .doxbrix/
│   └── config.json
├── docs.json
├── index.mdx
├── quickstart.mdx
└── guides/
    └── authentication.mdx

Complete example

This docs.json defines one versioned space with groups, a label, a divider, an external link and an API reference node.

{
  "version": 1,
  "name": "Acme Docs",
  "description": "Learn how to integrate with Acme.",
  "apiBaseUrl": "https://api.example.com",
  "openapiSources": ["openapi.yaml"],
  "versions": [
    { "version": "v2", "label": "v2.0", "tag": "Latest", "default": true },
    { "version": "v1", "label": "v1.x" }
  ],
  "spaces": [
    {
      "name": "Documentation",
      "slug": "docs",
      "locale": "en",
      "icon": "book",
      "version": "v2",
      "nav": [
        {
          "type": "group",
          "label": "Get started",
          "icon": "rocket",
          "items": [
            { "type": "page", "file": "index", "title": "Overview", "icon": "compass" },
            { "type": "page", "file": "quickstart", "icon": "bolt" }
          ]
        },
        { "type": "label", "text": "Guides" },
        { "type": "page", "file": "guides/authentication" },
        { "type": "divider" },
        { "type": "link", "title": "Service status", "href": "https://status.example.com", "icon": "globe" },
        { "type": "api", "title": "HTTP API", "spec": "openapi.yaml", "icon": "plug" }
      ]
    }
  ],
  "theme": {
    "primaryColor": "#6366f1",
    "lightColor": "#4f46e5",
    "darkColor": "#818cf8",
    "mode": "system",
    "font": "Inter",
    "codeFont": "JetBrains Mono",
    "logoLight": "/assets/logo-light.svg",
    "logoDark": "/assets/logo-dark.svg",
    "favicon": "/assets/favicon.svg"
  }
}

Top-level keys

Versions

Each entry in versions describes one product-docs version. The first entry is the default unless an entry sets default: true. To learn how readers switch versions, see Version your product documentation.

Spaces

A space is a top-level content section with its own navigation tree. For how spaces appear to readers, see Organize spaces, groups and navigation.

Navigation nodes

Every node has a type. A group can contain pages, links, labels, dividers, API nodes and nested groups.

hidden: true keeps a page or group out of the navigation sidebar.

Theme

All theme keys are optional. Use six-digit hexadecimal colors. Root-relative asset paths, such as /assets/logo-light.svg, resolve from the docs root. For the equivalent settings in the app, see Brand your site and choose a layout.

Colors and mode

Fonts and typography

Logos, icons and code

Layout

layout sets shell dimensions as numbers. When you include layout, set all six required keys.

Page files

Each page is an .mdx, .md or .markdown file with YAML frontmatter followed by Markdown or MDX content.

---
title: Authenticate requests
description: Send an access token with every API request.
pageType: how-to
---

Every request to the Acme API must include an access token.

<Steps>
<Step title="Create a token">Open **Settings** and create a token.</Step>
<Step title="Send the token">Add the `Authorization` header to each request.</Step>
</Steps>

Frontmatter

Because the title renders as the page heading, do not add a Markdown H1 to a page that has a title. Use at most one H1 in any page.

Components

Pages can use these Doxbrix MDX components. dxb lint warns about any other capitalized component tag outside code examples.

Accordion, AccordionGroup, AccordionItem, ApiEndpoint, Audience, Badge, Callout, Card, CardGroup, Check, CodeGroup, CodeTab, ColorGroup, ColorPalette, ColorSwatch, Column, Columns, Danger, Embed, Excalidraw, Expandable, File, FileNode, FileTree, Folder, Frame, Icon, Image, Info, Math, Mermaid, Note, PDF, Param, ParamField, ParameterTable, PromptCard, RequestExample, Response, ResponseExample, ResponseField, SidePanel, Step, Steps, Tab, Tabs, Terminal, Tile, Tip, Tooltip, Update, Video, ViewPane, ViewSwitcher, Warning.

For the equivalent blocks in the browser editor, see Blocks and slash commands reference.

Page types

Set pageType to opt a page into a machine-checkable page contract. dxb new page --type sets it for you. dxb docs check also infers a type from the path or title for untyped pages.

A missing contract section is a warning. An unsupported pageType value, or an explicitly typed page with no substantive content, is an error.

Lint rules

dxb lint runs these checks. Errors make the command fail. Warnings fail it only with --strict.

dxb lint --strict

Next steps