Publish the documentation site

The documentation is a Nimbus application deployed with Wrangler and the platform’s static-assets service. Publishing changes only the documentation Worker and its versioned assets.

Edit the right source

Author content under docs/. The documentation homepage is docs/README.md; the root repository README remains a local-development quickstart.

Keep these concerns separate:

• Managed service: customer onboarding and the hosted service’s boundaries.
• Build applications: shared organization workflows and Worker APIs.
• Self-hosting: local evaluation, installation, profiles, and bundled demos.
• Operations: maintaining an installation, customers, health, and certificates.

The publication map at examples/ermahgerd-docs/tools/navigation.mjs assigns source files to site paths and sidebar sections. The build converts repository links, copies media, and rejects unclassified Markdown pages. Nimbus scopes navigation to the current section; search can be limited to a section.

Generated content and copied media are ignored. Do not edit src/content/docs/ or maintain a second copy of a guide in the site source.

Validate the site

cd examples/ermahgerd-docs
npm ci
npm test
npm run typecheck
npm run build
npx --no-install @cloudflare/nimbus-docs check --json

This runs content-conversion checks, Astro checks, a production build, and Nimbus’s post-build audit. It does not require a running VM.

Refresh product screenshots

Product screenshots are authored evidence from the tenant and operator consoles, not mockups. With the local appliance running, refresh them through the Playwright tour:

npm --prefix apps/console exec -- playwright test browser-tests/docs-screenshots.spec.mjs

The tour writes reviewed PNGs to docs/screenshots/. Inspect the changed images before publishing, then run the site validation above. The Nimbus build copies those images into the generated site media automatically.

Publish to the managed installation

Configure Wrangler with https://api.ermahgerd.io/client/v4, your organization ID, and an organization read-write token. Then build and publish the application:

cd examples/ermahgerd-docs
npm ci
ERMAHGERD_DOCS_ORIGIN=https://docs.ermahgerd.io npm run build
npx wrangler deploy

For a browser tour of that deployment:

ERMAHGERD_DOCS_ORIGIN=https://ermahgerd-docs.t-bd7662a5eeb4.workers.ermahgerd.io \
  npm --prefix apps/console exec -- playwright test browser-tests/docs-site.spec.mjs

The tour checks section navigation, search filtering, refresh, themes, and mobile layout. Captures are retained under artifacts/playwright/console/.

Publish to a local installation

Configure Wrangler with https://api.ermahgerd.localhost:8443/client/v4, then:

cd examples/ermahgerd-docs
npm ci
npm run build
npx wrangler deploy
cd ../..
.cache/control-plane-venv/bin/python tools/check_docs_site.py
npm --prefix apps/console exec -- playwright test browser-tests/docs-site.spec.mjs

The application consumes Worker and static-assets allowances in its deployment organization; it needs no database or AI credentials.

To preview the site without a VM, run npm ci, then npm run dev in examples/ermahgerd-docs. Pagefind search requires a production build: use npm run build && npm run preview to preview search.

Set a different origin

ERMAHGERD_DOCS_ORIGIN controls canonical links, sitemap, social metadata, and machine-readable documentation. Set it to the complete origin that will actually serve the site. The Latitude helper supplies its public Worker origin; local builds default to the demo’s HTTPS origin.

Changing this build value does not create DNS, a certificate, or a custom-domain route. The platform currently serves tenant Worker hostnames; custom hostnames are not implemented. Configure the deployment connection separately using the Wrangler settings in Connect Wrangler.

Every guide has a Markdown version at /<page>/index.md; /llms.txt and section indexes describe the same content for automated readers.