Docs Site

The public WendyOS documentation site is built with Fumadocs and Next.js, then published as a static export to https://docs.wendy.dev.

URLs

Source Layout

The Fumadocs app is reached through docs/, which is a repository-root symlink to go/internal/cli/assets/docs. Top-level docs content lives as MDX and meta.json files in that tree. Existing lower-level Markdown reference files are still read from the same tree, but the prep script publishes them under the advanced/ section at build time.

docs/
  app/          Next.js app router routes, layout, and search
  components/   MDX components, search dialog, and providers
  guides/       Top-level guides and tutorials
  installation/ Top-level setup guides
  lib/          Fumadocs source loader and shared layout config
  scripts/      Content preparation for Fumadocs
  next.config.mjs
  package.json

Generated build output is ignored by git: content/, public/, .source/, .next/, out/, and export/.

Local Development

cd docs
npm ci
npm run dev

The dev server starts at http://localhost:3000/.

When editing source Markdown or MDX files, rerun the content prep script to refresh generated Fumadocs content:

cd docs
node scripts/prepare-content.mjs

Local Build

The deployed site uses a path prefix. Set NEXT_PUBLIC_BASE_PATH when testing a prefixed build:

cd docs
NEXT_PUBLIC_BASE_PATH=/branch-local npm run build

The static export is written to docs/out/.

CI And Deploy

The .github/workflows/fumadocs.yml workflow runs when docs, docs/**, go/internal/cli/assets/docs/**, or the workflow file changes.

Preview URLs are posted to same-repository PR comments and are visible to anyone who can read the PR. This is intentional; deploy paths are public preview paths and should not include sensitive information.

The deploy job authenticates to GCP with Workload Identity Federation and syncs static files to gs://wendy-docs-public/<deploy-path>. Static exports include SHA-256 manifests that are verified before each deploy path is synced. Release deploys attempt to enable bucket object versioning before updating latest/ or latest-nightly/ so alias overwrites remain recoverable. If the deploy identity lacks bucket-update permission, the deploy verifies the current state instead: it aborts only when versioning is confirmed disabled (an overwrite would be unrecoverable), and continues with a warning when versioning is already enabled out-of-band or cannot be read.

Required GitHub environment variables:

Hosting

Static files are served from the public wendy-docs-public Cloud Storage bucket through the global external HTTP(S) load balancer for docs.wendy.dev. The load balancer terminates HTTPS and adds security response headers for the public docs host.

Branch-preview objects under branch-* are cleaned up by CI after 30 days.

Release Notifications

The release workflow adds docs links to Discord notifications:

Validation

Run these before opening or updating a PR that changes the docs app:

cd docs
npm run types:check
npm run build