Developer Environment

This page explains the local setup for tiangong-lca-next-docs and how its Node baseline relates to the product repo at ../tiangong-lca-next.

If your work also involves aligning docs with product behaviour, continue with Docs / Product Sync Guide.

Node baseline

There are currently two baselines to keep in mind:

Docs site repo: package.json currently declares node >=18.0
Product repo ../tiangong-lca-next: the current engineering baseline is Node 24

Recommended approach

If you are only doing light maintenance in the docs repo, Node 18+ is technically enough.

If you also need to:

inspect the real implementation in ../tiangong-lca-next
switch between the two repos
investigate drift between docs and shipped behaviour

then use Node 24 across both repos to avoid version churn.

Install dependencies

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

nvm install 24
nvm alias default 24
nvm use 24

npm install --no-package-lock

The repository does not currently commit a package lock, so npm ci cannot bootstrap a clean checkout. Keep local installation lockfile-free unless a separate dependency-governance change intentionally introduces one.

Common commands

Local development

npm run start

The local site normally runs at http://localhost:3000/.

Markdown lint

npm run lint

Generate and check the AI docs index

npm run docs:llms
npm run docs:llms:check

docs:llms generates static/llms.txt from the public Docusaurus docs. docs:llms:check confirms that the committed index still matches the current public-doc source.

Check publication scope

npm run docs:publication-scope:check

This command checks static/llms.txt, sidebars.ts, context7.json, and build/llms.txt when a build exists. It prevents internal agent docs, TODOs, plans, incident records, or governance execution material from entering the public AI-consumption scope.

Check docs-impact screenshot evidence

npm run docs:screenshots:test
npm run docs:screenshots:check
npm run docs:screenshots:check -- \
  --manifest /tmp/docs-impact-visual-result.json \
  --diff-file /tmp/docs-impact-visual.name-status

docs:screenshots:test runs the screenshot-contract regression suite. Without a manifest, docs:screenshots:check confirms that the selected diff contains no documentation screenshot changes. For add, replace, or reuse evidence, pass the local visual result and the complete name-status diff. The validator checks page-local bilingual assets, references and alt text, nearby explanation in each language page, 144 DPI metadata, hashes, ratios, and action-specific diff state. The workspace validate-visual-evidence.rb remains responsible for validating the local 0600 access report used by the access-denied Draft exception.

Auto-fix lintable Markdown issues

npm run lint:fix

TypeScript check

npm run typecheck

Production build

npm run build

npm run build runs npm run docs:llms through prebuild first, so hosted platforms that only invoke the standard build command still publish an llms.txt file with the current build commit.

Serve the built site locally

npm run serve

Generate translation scaffolding

npm run write-translations -- --locale en

Minimum verification for doc changes

For public-doc content changes, run at least:

npm run lint
npm run docs:screenshots:check
npm run docs:llms:check
npm run docs:publication-scope:check
npm run build

If your change touches navigation, sidebar structure, links, or bilingual mirrors, also re-check:

docs/intro.md
docs/user-guide/overview.md
sidebars.ts

Release notes

The repository's .github/workflows/publish-docs.yml runs the post-merge publish loop on every push to main:

Generate and check static/llms.txt
Run the publication-scope check
Run lint, typecheck, and the Docusaurus build
Deploy Cloudflare Pages
Verify the public /llms.txt
Refresh Context7, or leave a visible follow-up when the secret is missing or refresh fails

The repository still keeps .github/workflows/build.yml for tag-triggered release publishing. Create and push a tag matching v* to trigger that flow.

git tag
git tag v0.0.1
git push origin v0.0.1

Cloudflare Pages deployment still depends on repository-level environment variables:

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID
CONTEXT7_API_KEY for automatic Context7 refresh. If it is missing, the workflow leaves a pending follow-up.

Optional repository variable:

CONTEXT7_LIBRARY_NAME, defaulting to the Context7 library id form /${{ github.repository }}

On this page