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.

https://docs.wendy.sh redirects to the equivalent https://docs.wendy.dev URL.

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.

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, redirects docs.wendy.sh to docs.wendy.dev, 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