Lint & validate

dxb lint checks your documentation for problems before you publish. It validates structure, frontmatter, links, and block usage — catching the issues that would otherwise produce a broken page on your live site. Run it locally as you write and in CI to gate every publish.

Run the linter

From your project root:

dxb lint

A clean run reports no problems:

✓ No problems found.

When there are issues, each is listed with its file and a description, ending in a count of errors and warnings.

What it checks

dxb lint covers the structural and block-validation checks the app runs when you publish, including:

• Missing files — a docs.json entry points to a non-existent .mdx file.
• Orphan files — an .mdx file not referenced in docs.json (won't publish until synced).
• Duplicate slugs — two pages resolving to the same URL.
• Broken links and images — internal links or images pointing at something that doesn't exist.
• Frontmatter problems — missing or malformed title / description.
• Unknown components — an MDX tag that isn't a real Doxbrix block.
• Heading structure — skipped levels or multiple H1s.

Errors vs. warnings

• Errors must be fixed — they would break the published site. Publishing refuses a project with lint errors.
• Warnings are advisory — they won't block a publish, but you should address them.

Use --strict to treat warnings as errors (exit non-zero), which is what you want in CI:

dxb lint --strict

For machine-readable output, add the global --json flag:

dxb lint --json

Linting in CI

Gate every publish on a clean lint:

# GitHub Actions
env:
  DOXBRIX_TOKEN: ${{ secrets.DOXBRIX_TOKEN }}
  DOXBRIX_PROJECT: my-docs
steps:
  - run: npm install -g @doxbrix/cli
  - run: dxb lint --strict
  - run: dxb push --publish

Lint vs. quality

dxb lint checks correctness — broken structure, links, and frontmatter. For content quality scoring (readability, structure, SEO, accessibility, completeness), use dxb quality or Scan with AI. Lint asks "is it valid?"; quality asks "is it good?"

Next steps