Skip to main content

​
Quick Checks

pnpm check:docs
pnpm docs:linkcheck
pnpm docs:validate
Run checks from the repository root unless the command explicitly changes into docs.

​
Common Issues

Symptom: page exists but does not appear in docs sidebar/tab structure.Fix: Add the page route to docs/docs.json and re-run mintlify validate to confirm structure integrity.
Symptom: pnpm check:docs fails on format or heading rules.Fix: Follow linter output line-by-line, keep heading hierarchy and list formatting consistent, and prefer native Mintlify components over custom HTML blocks.
Symptom: mintlify validate fails despite passing markdown lint.Fix: Check unsupported component syntax, verify tab/group/page mapping in docs/docs.json, and confirm all route links point to existing docs pages.
Symptom: the route exists, but Mintlify shows Page not found! and an unexpected error page.Fix: Reduce the page to standard Mintlify frontmatter (title, summary) plus supported Markdown or Mintlify components, then run pnpm docs:routecheck --base-url <preview-or-site-url> so you validate real route rendering instead of static checks only.

​
PR Checklist

1

Validate formatting and links

Run pnpm check:docs and pnpm docs:linkcheck.
2

Validate Mintlify routing and structure

Run pnpm docs:validate.
3

Smoke test real route rendering when debugging 500s

Run pnpm docs:routecheck --base-url http://localhost:3000 against a local preview, or point it at the deployed docs host.
4

Spot check key navigation paths

Confirm Docs Portal, FAQ, and Business as Agent are reachable.