---
title: "Publish the documentation site"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ermahgerd.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

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

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

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

```sh
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](/build/connect-wrangler/).

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

Source: https://docs.ermahgerd.io/operations/documentation/index.mdx