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

make docs-site-check

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

Publish to the reference managed installation

With the existing Latitude operator credentials available:

make latitude-docs-deploy

The target opens the configured private API connection, builds with the public canonical origin, deploys through Wrangler, and verifies the published pages over normal HTTPS. It does not run Ansible or redeploy the other examples.

For a browser tour of that deployment:

ERMAHGERD_DOCS_ORIGIN=https://ermahgerd-docs.t-bd7662a5eeb4.workers.ermahgerd.io \
  make docs-site-browser-check

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

Publish to a local demonstration

These targets use the local profile’s deployment connection and Worker origin:

make docs-site-deploy
make docs-site-test
make docs-site-browser-check

The local make up and make examples-deploy workflows also include this application. It 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 make docs-site-install, 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 targets 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.