Content doctor

contentbit doctor is the audit command to run before opening files by hand. It reads matched content once, validates registered blocks, checks frontmatter links, analyzes document structure, and prints the issues in repair order.

contentbit doctor

The content glob, registry, link fields, and SEO config come from contentbit.config.ts. Explicit globs and flags override it for one run.

The default report is meant for humans:

contentbit doctor
3 file(s): 1 errors, 1 warnings, 2 suggestions
2 linked page(s), 1 link(s), 1 orphan(s)

Repair plan:
1. [error] validation CB_PROPS_INVALID content/bad.md:8:1 - comparison: prop "left" Required
2. [warning] links CB_LINK_ORPHAN content/orphan.md:1:1 - page "orphan" has no inbound links
3. [info] stats CB_THIN_SECTION content/guide.md:24:1 - section "Deploy" has 3 words

What it checks

• Validation errors from the same registry path used by contentbit validate.
• Internal-link errors and warnings from slug, linksTo, aliases, locale/key options, and the same resolver modes used by contentbit links.
• Thin sections below --min-section-words (default 25).
• Block-less long documents with at least 250 prose words and no structured blocks.
• Missing image alt text from Markdown image syntax.
• Content integrity: duplicate frontmatter titles or descriptions, missing or multiple H1s on slugged pages, heading-level jumps, and unresolved local route/Markdown links or heading anchors. Multilingual libraries also flag missing stable keys and incomplete locale variants for a key.
• SEO contract findings when contentbit.seo.config.ts exists or --seo-config is passed.

doctor is read-only. It does not write .contentbit/link-index.json, and it does not run links --fix. If aliases are present and the link graph has no errors, the text report suggests the fix command explicitly.

Watch while editing

Run Doctor continuously during an edit session:

contentbit doctor --watch

It prints the first report immediately, then reruns after a change in a directory that supplied an initially matched content file. Watch mode is local feedback only; use the ordinary command with strict flags for CI.

JSON for agents and CI

Use --json when an LLM agent or pipeline needs stable data:

contentbit doctor --json

The shape is:

{
  "files": 3,
  "summary": { "errors": 1, "warnings": 1, "suggestions": 2 },
  "linkGraph": { "pages": 2, "links": 1, "orphans": 1 },
  "findings": [
    {
      "severity": "error",
      "source": "validation",
      "code": "CB_PROPS_INVALID",
      "file": "content/bad.md",
      "line": 8,
      "column": 1,
      "message": "comparison: prop \"left\" Required"
    }
  ]
}

Exit codes match its job as a health gate:

• 0 when there are no error findings.
• 1 when there are error findings, or when --strict-warnings is passed and warnings are present.
• 1 when --strict-seo is passed and SEO warnings are present.
• 2 when no files or globs were provided, or no files matched.

How it fits

Use doctor to decide what to fix first. Use validate when you only need the blocking syntax/schema gate. Use links when you need to write the link index or heal alias references. Use stats when you need raw per-document metrics. Use Programmatic SEO workflows when you want to plan pages with briefs and enforce SEO contracts in CI. For the full option list, see the CLI reference.