Skip to main content

Documentation

This guide owns docs placement, the doc rules, i18n, docs sync, the coverage lifecycle and the link strategy.

Placement and rules

  • English source lives in docs/. docs/zh-CN/** and docs/ja-JP/** are generated; do not edit them directly.
  • i18n pipeline: update the English page, adjust docs/.i18n/glossary.zh-CN.json, then run scripts/docs-i18n.
  • Internal doc links are root-relative with no .md or .mdx extension, for example [Config](/configuration). When a page is mapped to a different site route, use its absolute https://docs.wednesdayai.dev/... URL so unchanged sync output targets the published page.
  • Headings avoid em dashes and apostrophes, because they break anchor generation.
  • Content must be generic: no personal device names, hostnames, or paths. Use placeholders such as user@gateway-host.
  • Store screenshots under docs/.screenshots/ (gitignored). Never commit screenshots or leave them at the repo root.
  • Frontmatter uses title, summary and read_when. Developer pages add audience: developer.
  • After editing docs, run pnpm check:docs (format, docs lint and the link audit). pnpm docs:list lists docs for a quick sanity check.
  • When code, a README or a skill links to https://docs.wednesdayai.dev, run pnpm docs:check-site-links. It needs network access. It checks every such link the repo emits against the live site’s sitemap.xml and page anchors, and reports any route missing from site navigation or any anchor missing from its page. It also runs weekly (.github/workflows/docs-site-links.yml) and opens a docs site link gaps issue. A route that fails only because the page is not synced yet clears once scripts/docs-sync.sh publishes it.

Docs sync

The docs site repository (ExpansionX/WednesdayAI-docs, Mintlify at docs.wednesdayai.dev) holds three versions of the same pages:
  • The latest release sits at the root (admin/, users/, developers/, reference/, index.mdx, changelog.mdx). It is the default version, so its URLs never change.
  • next/ is the unreleased version. scripts/docs-sync.sh rebuilds it from one core main SHA after every core merge.
  • vA.B/ directories pin older release minors, newest first.
Edit core, never the docs repo, for any synced page. A fix made in the docs repo is overwritten by the next sync. scripts/docs-sync.sh syncs English core docs to the site through the single mapCoreDocToPersona mapping in scripts/docs-drift.mjs (gateway/ to admin/gateway/, CONTRIBUTING.md to the single page developers/contributing, and so on). Only pages listed in a dev-docs/wai-feature-list.json feature under core_doc_paths are synced; scripts/docs-sync.test.ts enforces that every docs-surface.yaml entry whose docs_page is the persona-mapped target of its core source is covered. When the site page already exists, scripts/docs-sync-frontmatter.mjs merges the frontmatter: core keys win and site-only keys (description, sidebarTitle) are kept. Two gates run in core before anything is published:
  • pnpm docs:check-mdx compiles every published core doc with @mdx-js/mdx (issue #2519). HTML comments and bare <word> placeholders in prose fail; use the repo’s MDX comment form {/_ note _/ && null} (oxfmt-stable in .md) and backticks instead.
  • pnpm docs:check-published-links resolves every internal link and image of the published docs against core. A link must reach a published core doc, an existing asset, or a docs-repo page route.
After a core PR merges, run scripts/docs-sync.sh once from the repo root. It rebuilds next/ from a single core SHA on a fresh docs-sync/next branch, force-pushes, and squash-merges its own PR; never merge docs-sync PRs by hand. It skips the run when docs next is already at or past that SHA, and it exits with guidance when the site has no versions yet. The one-time bootstrap is scripts/docs-sync.sh --release <latest tag> --ref origin/main: --ref overrides the release source when the tag predates a sync fix, and the run prints the override. scripts/docs-sync.sh --dry-run prints the mapping and pushes nothing; --feature <slug> narrows a dry run only. scripts/docs-sync.sh --release vX.Y.Z cuts the default version from the tag. On a minor bump it snapshots the previous root to vA.B/; retention keeps four minors (the latest at the root plus three snapshots) and a pruned version redirects /vX.Y/:slug* to /:slug*. It sets the release banner, opens the docs: WednesdayAI vX.Y.Z PR, and merges it only once the GitHub release is published (not draft): rerun the command after publishing. See Release. Adding a new page takes two steps: add the core doc to the feature’s core_doc_paths in dev-docs/wai-feature-list.json, then add the page to the next version’s navigation in the docs repo’s docs.json (next mode never edits docs.json). At release, the root navigation takes over whatever next carried. The sync rewrites internal links and images to their own version prefix and copies images to content-addressed media/ paths shared by every version.

Docs coverage lifecycle

  • Source of truth: docs-surface.yaml at the repo root maps every documentable surface (hook, SDK export, config key, channel, provider, CLI command, concept) to its expected docs page. It is the single mapping; the docs repository never holds a second copy.
  • Two tiers:
    1. A cheap deterministic gate, scripts/docs-surface-check.mjs, runs locally before a PR (the core docs-surface.yml workflow is archived; ADR 2399). node scripts/docs-surface-check.mjs --mode=source checks that each source path still exists. --mode=pages --docs-root=<docs checkout> (docs CI) checks that each docs_page, plus optional #anchor, resolves.
    2. A periodic deep audit, a manual review of real surfaces against docs-surface.yaml, finds new undocumented surfaces that the cheap gate cannot see.
  • Advisory only: branch protection is unavailable on the free-plan private repo, so the check never hard-fails a merge. It exits 0 and prints warnings. --strict (pnpm docs:surface:strict) gives a non-zero exit.
  • Cadence: run the cheap gate before each PR that touches a documentable surface. Run the deep audit each release cycle and after large surface changes.
  • Follow-ups: a detected gap becomes a tracked follow-up, keyed by the surface id so it is idempotent: a GitHub issue (label docs-coverage). Entries with coverage: gap or wrong carry the known-bad baseline until a docs PR flips them to documented.
The core repository is private. A link resolves only if the reader can reach its target. SUPPORT.md and the CONTRIBUTING.md rendering state the security contact (security@expansionx.com.au) inline, so the public path never depends on reading SECURITY.md.