Skip to main content

Documentation audit

Audit date: 2026-05-29

Scope​

This audit checked the current checkpoint repository against the docs in this repository. checkpoint is a Docusaurus documentation portal; it does not contain the BitView application, backend, on-chain, or identity service source trees that many product docs describe.

Current repository architecture​

  • Docusaurus 3.10 site configured by docusaurus.config.js.
  • React 19 landing page in src/pages/index.tsx.
  • Tailwind CSS v4 is loaded through the custom PostCSS plugin in docusaurus.config.js and global imports in src/css/custom.css.
  • The primary docs plugin serves docs/ at /docs with an autogenerated sidebar from sidebars.js.
  • A second @docusaurus/plugin-content-docs instance serves guides/ at /guides with an autogenerated sidebar from sidebars-guides.js.
  • Docusaurus blog content in blog/ is served at /blog.
  • Static assets under static/ are copied into the build output.
  • The only repository-specific environment switch is BUILD_PUBLIC=true, which excludes docs/_internal/** from the primary docs plugin before sidebar and route generation.

Findings​

Accurate​

  • package.json accurately lists the available Docusaurus scripts: start, start:public, build, build:public, build:internal, serve, deploy, clear, typecheck, and Docusaurus helper scripts.
  • docusaurus.config.js accurately implements the public/internal split with BUILD_PUBLIC=true and exclude: ["**/_internal/**"] for public builds.
  • The docs and guides sidebars are autogenerated from file structure.
  • The documented public docs routes (/docs, /guides, /blog) match the Docusaurus configuration.
  • Internal docs can safely link to public docs, and public docs should not link directly to docs/_internal/** because those routes are absent from public builds.

Wrong, missing, or outdated​

  • README.md said the site was built with Docusaurus 2; the current dependency is Docusaurus 3.10.
  • README.md only documented the default local start/build commands and omitted the public/internal build modes, BUILD_PUBLIC=true, the separate guides docs plugin, the blog route, and the current content layout.
  • docs/_internal/README.md used npm run ... examples even though the repo is pinned to pnpm@8.15.8 via packageManager and all top-level docs use pnpm.
  • One public identity page linked directly to an internal _internal document; the public build excludes that target, so the link was replaced with plain text pointing readers to the internal doc by path.
  • pnpm typecheck currently fails before checking site source because the TypeScript configuration references missing type packages (@docusaurus/theme-classic and node) and TypeScript 6 reports the deprecated baseUrl option. This is a repository configuration issue, not a docs-command issue; the build commands still succeed.

Fixes made​

  • Updated README.md to describe Docusaurus 3, Node/pnpm requirements, install/start/build commands, public/internal build behavior, routes, and content layout.
  • Updated docs/_internal/README.md examples from npm run ... to pnpm ... and corrected the public-build leakage check to assert that no generated build/docs/_internal route exists.
  • Updated the operations page's documentation-site deploy section to use the current Docusaurus 3 public/internal build commands.
  • Removed the direct public-to-internal markdown link in docs/technical/identity.md while preserving the internal reference by path.
  • Added this audit report.

Verification​

Commands run from repository root:

corepack pnpm --version
corepack pnpm typecheck
corepack pnpm build
corepack pnpm build:public
test ! -e build/docs/_internal && echo 'public-build-no-internal-route: clean'

Results:

  • corepack pnpm --version reported 8.15.8.
  • corepack pnpm build succeeded and generated build/.
  • corepack pnpm build:public succeeded and generated build/ with BUILD_PUBLIC=true.
  • The public build did not generate a build/docs/_internal route.
  • corepack pnpm typecheck failed with existing TypeScript configuration/type dependency errors: missing @docusaurus/theme-classic types, missing node types, and TS5101 for deprecated baseUrl under TypeScript 6.