The docs app lives in the repository's pnpm workspace and uses the shared OSS-site foundation: Chakra UI 3, Chakra Docs, Postkit, Shiki, Suisse fonts, and the COMMUNE and OSS footers. It has no site CSS files.
From the repository root:
nvm use
corepack enable
pnpm install --frozen-lockfile
pnpm run docs:devThe default development address is http://localhost:3000. The Next config
also allows react-structured.test for a local reverse proxy. The site respects
system color mode; there is no manual theme switch. Ensure the shared Fontstack
kit permits the production and local domains.
The committed Chakra Docs dependencies use pinned public releases. To test local changes to Chakra Docs, publish the packages to your yalc store and link them in the docs workspace:
cd docs
yalc add --no-pure @chakra-docs/chakra @chakra-docs/core @chakra-docs/next @chakra-docs/search @chakra-docs/shiki @chakra-docs/source-filesystem
cd ..
pnpm install --no-frozen-lockfileYalc copies and registrations are intentionally untracked. Remove local links and restore the committed public versions before running docs CI or deploying.
Documentation lives in content/*.md. Frontmatter owns the title, description,
and navigation order. Do not duplicate the page title or description at the top
of the body. Use ## for the first body heading. Markdown is rendered through
Postkit; code blocks, callouts, permalinks, layout, navigation, search, and page
actions use Chakra Docs. Raw HTML is inert, and executable MDX is unsupported.
Page actions use automatic composition and download Markdown from real,
generated /markdown/<slug>.md endpoints. They do not assume that a docs page
also has a .md route.
/llms.txt indexes the published docs using their real /markdown/<slug>.md
endpoints. /llms-full.txt includes their complete Markdown bodies. Both are
generated from the docs manifest into docs/out at build time and exclude draft
and hidden content. docs:verify validates the files and their links. Rebuild
and deploy the site after editing docs; no npm publish is needed.
pnpm run docs:tooling
pnpm run docs:build
pnpm run docs:test
pnpm run docs:typecheck
pnpm run docs:verify
pnpm run docs:release-checkdocs:verify also serves the generated static artifact on a temporary loopback
port and checks real HTTP GET/HEAD responses, canonical metadata, JSON-LD,
crawler and LLM files, Markdown, and missing-page status codes. Run
pnpm run docs:smoke separately after an existing build. This validates the
artifact and clean-URL hosting contract; it does not inspect Vercel dashboard
settings or replace a post-deployment smoke check.
Deploy docs/out to react-structured.dev. For Vercel, use docs as the project
root; vercel.json checks public dependencies, installs the workspace, and builds
the library before the site. Keep the Framework Preset set to Next.js and the
Output Directory override off in Vercel's project settings. The Next.js adapter
reads build manifests from .next and handles the static export automatically;
setting its Output Directory to out makes it look for those manifests in the
wrong folder. docs/out remains the exported site for other static hosts.
Production installs must not depend on a local yalc store. The manual Documentation checks workflow runs the same public-dependency guard and uploads the static site after validation.
pnpm test and pnpm run test:ci run only the library tests; package coverage
does not include the private docs app. pnpm run test:tooling checks package
tooling without loading docs code, so prepublishOnly can verify a library-only
install. pnpm run docs:tooling checks docs tooling, including LLM files,
recommendations, analytics, and dependency guards. pnpm run docs:test runs the
docs unit tests separately, including navigation, metadata, and JSON-LD. Install the full
workspace and run pnpm run build first: these tests use the built local library
through its public package exports. Both CI and Documentation checks run the
docs suites; filtering the install to the root library is only appropriate for the
library-only publish workflow.
The site emits canonical/Open Graph/Twitter metadata, robots.txt, a sitemap,
and a generated fallback PNG. Set NEXT_PUBLIC_OG_IMAGE_BASE_URL at build time
to use an external opengraphs.com renderer for page-specific PNGs. Configure it
to capture these real HTML routes:
/social-image/docs/social-image/docs/<slug>/social-image/withoss/social-image
Alternate capture templates are available at /og-image and
/og-image/docs/<slug>. Capture pages are noindex, have no site chrome, and
expose data-og-ready="true" after fonts and SVG assets are ready. Static routes
are generated at build time; no unsupported Next.js static-export rewrites are
used.
Set NEXT_PUBLIC_FATHOM_SITE_ID and optionally
NEXT_PUBLIC_FATHOM_CUSTOM_DOMAIN before building. React Fathom tracks initial
loads, App Router navigation, and docs interaction events. Empty IDs disable
network analytics. Query strings, fragments, search text, clipboard contents,
and feedback comments are not sent. OG capture pages bypass analytics.
The site pins the published react-fathom@0.3.0 and Chakra Docs 0.3.0 releases.
No local yalc copies of these packages are needed for a clean CI or deployment
install.