Docs Publishing
The documentation site lives in the independent soha-docs repository and uses Next.js with Nextra. Release docs are published independently from the soha core binary and web artifact.
The active site uses Nextra’s official docs-theme i18n flow. Chinese content lives under content/zh, English content lives under content/en, and public routes are locale-prefixed:
/zhand/zh/docs/.../enand/en/docs/...
proxy.ts exports proxy from nextra/locales, so / and /docs/... redirect to the best locale from NEXT_LOCALE or the browser language.
Commands
cd soha-docs
npm install
npm test
npm run typecheck
npm run build
npm run serveDocumentation must evolve with code changes. Architecture, API, and development guides are first-class project assets.
The site is a standard Next.js build. It is not exported to out/, and it is not deployed through GitHub Pages. Publish the build with a Node-capable Next.js host such as Vercel, using the repository root soha-docs, build command npm run build, and the host’s automatic Next.js output detection.
The soha core repository must not import this source tree. By default, soha serves the API and embedded Web console, then redirects /docs/ to the configured external docs URL. Development and private deployments may still use docs proxy or dir asset modes when needed, but release docs are treated as an independent site.
Build-Time Environment
next.config.mjs reads these build-time variables:
DOCS_SITE_URL: published origin. Default:https://docs.opensoha.devDOCS_BASE_URL: published path prefix. Default:/DOCS_SHOW_LAST_UPDATE_TIME: retained as a workflow variable for release compatibility; Nextra does not currently render it.
For https://docs.opensoha.dev/, use:
DOCS_SITE_URL=https://docs.opensoha.dev DOCS_BASE_URL=/ npm run buildFor https://opensoha.dev/site/, use:
DOCS_SITE_URL=https://opensoha.dev DOCS_BASE_URL=/site/ npm run buildQuality Gates
The Search quality gate is based on Nextra’s local Pagefind-backed search. next.config.mjs keeps search enabled while excluding code blocks from the index, and scripts/verify-docs-drift.mjs checks that the publishing notes and config stay aligned. Release builds do not require external Algolia credentials.
The broken-link gate has two layers: the Nextra/Next build validates routable pages, and scripts/verify-docs-drift.mjs scans relative Markdown links during npm test.
The Screenshot regression gate is driven by
quality/docs-screenshot-regression.json. The manifest records the required
desktop and mobile viewport coverage, source document for each route, and the
DOM/content assertions checked against built HTML. The current checker does not
capture screenshots or execute viewport-specific browser interactions.
After a local or CI build, run npm run screenshots:check to verify the
rendered Nextra routes against the checked-in baseline records under
quality/screenshots/baseline. When an intentional docs or Web-facing route
change alters route metadata, assertions or the accepted minimum content size,
review the change before updating the baseline:
npm run build
npm run screenshots:update
npm run screenshots:checkThe baseline records store route, viewport, source path, assertion set and a minimum rendered HTML length. Content growth does not require a new baseline; content below that floor, changed metadata and missing assertions still fail. These text records contain no source or HTML hashes and do not prove visual or interactive acceptance. Review actual pages separately for visual changes.
Hosting Workflow
The release publishing path is a host-managed Next.js deployment, not GitHub Pages.
- Connect the
soha-docsrepository to the Next.js host. - Set the project root to
soha-docs. - Use
npm run buildas the build command. - Leave the output directory empty or automatic so the host detects Next.js.
- Configure the production domain as
docs.opensoha.devin the host and DNS provider. - Do not add
public/CNAMEor.github/workflows/publish.yml; those are GitHub Pages-specific artifacts. - The CI workflow checks out the pinned
opensoha/sohaRoot revision next tosoha-docs; contracts inputs are read from../soha/contracts. - Verification before deploy:
npm ci,npm run typecheck,npm test, andnpm run build.
Set deployment environment variables when publishing outside the defaults:
DOCS_SITE_URLDOCS_BASE_URLDOCS_SHOW_LAST_UPDATE_TIME
The CI workflow uses the same pinned Root checkout and runs docs consistency tests against its contracts/ module before every build.
English Content Strategy
The active Nextra site uses locale-aware content roots now. Chinese source is content/zh; English source is content/en. Legacy Docusaurus translation directories are not part of the active source tree after the Nextra docs-theme rebuild.
When changing translated content, keep search indexing, canonical URL changes, and deployment environment variables explicit in the Next/Nextra config and CI workflow.