Docs Check

Docs Check

Validate the GitHub Pages documentation site produced by @docmd/core.

Quick Reference

Prerequisites

• Node.js 18+ (for npx @docmd/core)
• The repo root as working directory
• Optional: npx serve or similar for local preview

Mindset

Documentation is only as valuable as it is discoverable. A broken build, orphan pages, missing index entries, and stale references each silently erode trust in the site. Treat every check as a gate: if it fails, the user loses confidence.

• Build first, ask questions later. Always start with the build check — it is the fastest path to failure and catches mechanical issues early.
• Automate what you check twice. If you catch the same issue twice, TYPICALLY you should add a script or CI step so you NEVER check it manually again.
• Fix the source, not the output. When a check reveals a problem, fix the markdown source, not the built site/ — the build is ephemeral.
• Escalate to the right skill. When content quality issues surface, redirect to markdown-authoring; when skill documentation is the concern, redirect to skill-quality-auditor. For quick formatting-only issues, PREFER using markdownlint directly.
• Adapt to the situation. UNLESS the CI deployment is already broken, you may skip the build check for trivial doc tweaks (single-word fixes, typo corrections).

When to Use

• After editing or adding docs/ content
• Before pushing doc changes to main
• When the docs CI workflow fails
• When adding or renaming pages
• When ADRs are added without updating docs/ADR/index.yaml
• Before a release to verify the published site is complete

When Not to Use

Checks

1. Build check

npx @docmd/core build

Expected result: exit code 0, output written to ./site/.

If the build fails, inspect the error output — common causes include broken links, invalid YAML frontmatter, or missing referenced files.

After a successful build, confirm the page count is reasonable (typically 45-55 pages for this project). A sudden drop signals missing content.

2. Preview

npx @docmd/core dev

Opens a dev server at http://localhost:3000 with hot reload. Browse the site and verify:

• All navigation links work
• New pages appear in the expected section
• No broken internal links
• Content renders correctly

Stop the dev server with Ctrl+C.

3. Orphan detection

Pages in docs/ that are not linked from any index are invisible to site visitors. Check for orphans:

# List all markdown files under docs/ (excluding ADR index.yaml)
find docs/ -name '*.md' ! -name 'index.md' | sort > /tmp/all-pages

# Extract linked references from the index page
rg -o '\([^)]+\)' docs/index.md | rg -o '[^()]+' > /tmp/linked-pages

# Find orphans
comm -23 /tmp/all-pages /tmp/linked-pages

Any file in the output is an orphan — add a link from docs/index.md or a subsection index.

4. ADR index freshness

Every ADR file in docs/ADR/ should be registered in docs/ADR/index.yaml:

# List ADR files (expect adr-NNN-*.md)
ls docs/ADR/adr-*.md 2>/dev/null | sed 's|docs/ADR/||' > /tmp/adr-files

# Extract registered ADRs from index.yaml
grep 'adr:' docs/ADR/index.yaml | sed 's/.*adr: //' > /tmp/adr-indexed

# Find unregistered ADRs
comm -23 <(sort /tmp/adr-files) <(sort /tmp/adr-indexed)

Unregistered ADRs should be added to docs/ADR/index.yaml. Use the adr-capture skill to generate the entry.

Also check for stale index entries (ADRs listed in index.yaml but missing from disk):

comm -13 <(sort /tmp/adr-files) <(sort /tmp/adr-indexed)

Entries in this output reference files that no longer exist — remove them from index.yaml or restore the files.

5. LLM output audit

When llms.enabled is true in docmd.config.json, the build generates llms.txt, llms-full.txt, and llms.json in the output directory. Verify they exist and contain expected entries:

# Check files exist
test -f site/llms.txt && echo "llms.txt: OK" || echo "llms.txt: MISSING"
test -f site/llms-full.txt && echo "llms-full.txt: OK" || echo "llms-full.txt: MISSING"
test -f site/llms.json && echo "llms.json: OK" || echo "llms.json: MISSING"

# Count entries
grep -c '^- \[' site/llms.txt 2>/dev/null || echo "llms.txt has no entries or is missing"

6. Cross-reference integrity

Reference files in cmd/assets/references/ are embedded assets used by the CLI at runtime. If any should also appear on the doc site, verify they have corresponding pages under docs/:

ls cmd/assets/references/*.md | sed 's|cmd/assets/references/||' > /tmp/asset-refs
find docs/ -name '*.md' -exec basename {} \; | sort > /tmp/docs-pages
comm -12 /tmp/asset-refs /tmp/docs-pages

The output shows files present in both locations — these should be kept in sync.

Workflow

1. Build check — confirm the site compiles. If it fails, triage the error and fix before proceeding.
2. Orphan detection — find and link any unlinked pages. If orphans exist, add links to docs/index.md.
3. ADR index freshness — reconcile on-disk ADRs with the index. Use adr-capture to register missing entries.
4. LLM output audit — verify machine-readable outputs exist with non-zero entries.
5. Preview — final manual review in browser before pushing.
6. Commit and push — the CI workflow deploys automatically when docs/** or docmd.config.json changes on main.

Anti-Patterns

NEVER skip the build check before pushing

WHY: A broken build blocks the deployment CI job and requires a separate fix commit, wasting time and polluting git history.

SYMPTOM: Doc changes are pushed without a local build, and the CI deployment step fails with a cryptic error.

CONSEQUENCE: The deployment is blocked until a fix commit is pushed, adding latency and noise to git history.

BAD: Editing docs/index.md, committing, and pushing without running the build first.

GOOD: Run npx @docmd/core build locally before pushing doc changes.

NEVER leave orphan pages unlinked

WHY: Orphan pages are invisible to navigation and search, wasting the effort spent writing them.

SYMPTOM: A documentation page you wrote never appears in search results or navigation menus.

CONSEQUENCE: Site visitors cannot discover the content, so the writing effort is wasted.

BAD: A new docs/architecture/deployment-flow.md exists but is not linked from docs/index.md — it compiles but no visitor can reach it.

GOOD: Add a link from docs/index.md or the relevant subsection index. Run the orphan detection command to confirm.

NEVER add an ADR without updating the index

WHY: The ADR index is the canonical discovery mechanism; a missing entry means the ADR may as well not exist.

SYMPTOM: A reviewer asks "is there an ADR about this?" and the index query returns empty, even though the file exists on disk.

CONSEQUENCE: The ADR is invisible to automated discovery and humans navigating the index, defeating the purpose of documenting the decision.

BAD: Creating docs/ADR/adr-026-new-format.md without adding an adr entry to docs/ADR/index.yaml.

GOOD: Add the ADR file and register it in docs/ADR/index.yaml in the same commit. Use the adr-capture skill to generate the correct YAML entry.

NEVER reference a page that does not exist

WHY: Broken links degrade trust in the documentation and produce 404s for visitors, eroding confidence in the entire project.

SYMPTOM: Clicking a link on the site leads to a 404 page instead of the expected content.

CONSEQUENCE: Visitors lose trust in the documentation and may stop relying on it as an authoritative source.

BAD: Linking to architecture/new-flow.md in docs/index.md when the file was renamed to architecture/updated-flow.md.

GOOD: Use relative paths and verify the target file exists before committing. After renaming files, update all inbound links.

References

Troubleshooting