Running and hosting the wiki

Local use

Install Node.js 22 or newer, then run these commands from the repository root:

npm install
npm run docs:dev

Open the local address printed by VitePress. The server binds to 127.0.0.1 by default. Stop it with Ctrl+C. For a repeatable installation in automation, use npm ci with the lockfile.

npm run docs:check
npm run docs:build
npm run docs:preview

The check validates Markdown page links and navigation coverage. The build generates the static site in dist/; preview serves that built output locally. No firmware or game application is built by these commands.

Layout and features

Pages live under docs/; configuration and the small theme customization live under docs/.vitepress/. The root README remains useful in Git. Local search indexes the documentation in the built site.

Mermaid diagrams use fenced mermaid blocks. Ordinary code blocks and Markdown tables remain readable in Git. Images can live beside their page and use relative Markdown paths; shared public assets can live in docs/public/. No PCB schematics or product photographs have been fabricated.

VitePress provides the static documentation framework. VitePress Plugin Mermaid adds diagram rendering. Installed versions are recorded in the lockfile.

Hosting

The public wiki is hosted at Smart Catan using Sites. The project association and static output directory are recorded in .openai/hosting.json. Future updates require a new build and publication through Sites; local edits are not published automatically.

For an alternative static host, use:

Setting	Value
Install	npm ci
Build	npm run docs:build
Publish directory	dist
Site root	Repository root for install/build
Runtime	Node.js 22 or newer

GitHub Pages, Netlify, or Vercel can host the static output. An alternative provider can use the same static build. Do not upload the source folder as the public artifact.

The default site base is /. For a repository subpath, set DOCS_BASE with leading and trailing slashes when building, for example:

DOCS_BASE=/smart-catan/ npm run docs:build
DOCS_BASE=/smart-catan/ npm run docs:preview

Use / for a root domain. Hosting this wiki does not host the game engine, game API, or player applications. See VitePress site configuration for the base-path setting.