Skip to main content

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

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 ci

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.

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: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:

  1. Generate and check static/llms.txt
  2. Run the publication-scope check
  3. Run lint, typecheck, and the Docusaurus build
  4. Deploy Cloudflare Pages
  5. Verify the public /llms.txt
  6. 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 }}