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.

Vanity redirects

Short marketing paths are served as static redirect pages uploaded to the bucket root by the Deploy vanity redirects step in .github/workflows/fumadocs.yml (main-branch pushes and release deploys only):

Add new entries to the REDIRECTS map in that workflow step. Slugs must not collide with deploy path prefixes (latest, latest-nightly, release-*, branch-*).

Security headers

The load balancer adds these headers to every docs.wendy.dev response. They are custom response headers on the backend bucket wendy-docs-backend, which the URL map wendy-docs-url-map routes docs.wendy.dev to, in the GCP project from vars.GCP_PROJECT_ID. No file in this repository manages them. install.wendy.dev and templates.wendy.dev share the load balancer but use other backend buckets without these headers.

default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; frame-src https://www.youtube.com https://www.youtube-nocookie.com; img-src 'self' data: blob: https://www.googletagmanager.com https://*.google-analytics.com; font-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' https://www.googletagmanager.com; connect-src 'self' https://www.googletagmanager.com https://*.google-analytics.com https://*.google.com; worker-src 'self' blob:

What the policy means for docs changes:

• Images must come from the docs site itself. Commit them to the docs tree instead of linking to another host. The YouTubeVideo component uses local thumbnails in images/youtube/ for this reason.
• Iframes can only embed YouTube.
• The Google Analytics hosts follow Google's list for GA4 without Ads features. Until 2026-09-27 the policy blocked gtag.js, so docs page views before that date were not recorded. Turning on Google Signals or linking Google Ads needs more hosts.

Read the current headers:

gcloud compute backend-buckets describe wendy-docs-backend \
  --project=<GCP_PROJECT_ID> --format='yaml(customResponseHeaders)'

To change a header, pass the complete list. gcloud compute backend-buckets update --custom-response-header replaces every custom header, so any header you leave out is removed:

gcloud compute backend-buckets update wendy-docs-backend --project=<GCP_PROJECT_ID> \
  --custom-response-header="X-Content-Type-Options: nosniff" \
  --custom-response-header="X-Frame-Options: DENY" \
  --custom-response-header="Referrer-Policy: strict-origin-when-cross-origin" \
  --custom-response-header="Permissions-Policy: camera=(), microphone=(), geolocation=()" \
  --custom-response-header="Content-Security-Policy: <complete policy>"

Changes reach responses within a few minutes, including responses the CDN has already cached, so no cache invalidation is needed. Verify with curl -sI https://docs.wendy.dev/latest/, then open a docs page and confirm the browser console shows no Content Security Policy errors.

Agent Docs (llms.txt)

Each deploy path also publishes Markdown for AI agents. The "View raw Markdown" and "Agent docs index" page actions link to these files.

scripts/publish-markdown.mjs writes these files during content preparation. Stable release deploys also copy latest/llms.txt and latest/llms-full.txt to the site root, where agents look first, in the Publish root llms.txt step of .github/workflows/fumadocs.yml. Nightly releases and branch previews leave the root copies unchanged.

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