Check your docs

Check the docs tree, links, overlaps, read size, and CLI peer.

Run the docs check

Run doctor integration docs in your package to check the docs tree, every link, and overlaps with Core topics. Pass a package name to check an installed package.

bash
npx astryx doctor integration docs
# In an app, check an installed package
npx astryx doctor integration docs @acme/astryx-widgets

text
Checking integration docs: @acme/astryx-widgets@1.0.0
[ok] The docs tree and every link in these docs check out.
[ok] No doc topics overlap with Core.

Its arguments and exit codes are in astryx docs cli/commands/doctor-integration-docs.

Know what fails the check

A doc that does not load, an accidental Core overlap, or a failed namespace or placement fails the check with exit code 1. A link that names no doc only warns, and the exit code stays 0.

Problem	Reported as	Exit code
A doc that does not load, such as an unknown section field or block type	`[fail]` `invalid_doc`	1
A topic with a Core topic's name and no `replaces` or `extends`	`[fail]` `accidental`	1
A placement that fails, which hides the doc	`[fail]` `invalid_doc_graph`	1
A link that names no doc	`[warn]` `invalid_doc_graph`	0
A topic that sets `replaces` or `extends`	`[info]` `replaces` or `extends`	0

Read the warnings before you publish. With --json, they are in data.issues, with severity: "warning".

Check read size

npx astryx doctor also measures every read and warns on one over 32 KB. Run it in your package or in an app that installs it; doctor integration docs does not check size.

bash
npx astryx doctor

text
id:      docs-progressive-disclosure
status:  [warn]
label:   Documentation navigation and size
message: acme/deploying build-before-you-ship: 46 KB, over the 32 KB one read may return

Split a section over the limit into smaller ones, each with its own key. See astryx docs cli/commands/doctor.

Check the CLI peer

integration verify fails a package that ships a docs section, a placed guide, or a doc section with an id without an @astryxdesign/cli peer of >=0.7.0. It does not run the docs check, so run both.

bash
npx astryx integration verify

text
- [fail] The package ships a namespace doc or a placed guide but declares no @astryxdesign/cli peer. A stable CLI before 0.7.0 does not read the docs tree, and can hide every doc topic the package ships. Declare "@astryxdesign/cli": ">=0.7.0" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required).

integration add doc --parent writes the peer for you.
integration verify passes a hidden guide and an accidental Core overlap; only doctor integration docs catches them.
Everything else it checks is in astryx docs cli/commands/integration-verify and astryx docs cli/integrations/ship/checks.