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/**anddocs/ja-JP/**are generated; do not edit them directly. - i18n pipeline: update the English page, adjust
docs/.i18n/glossary.zh-CN.json, then runscripts/docs-i18n. - Internal doc links are root-relative with no
.mdor.mdxextension, for example[Config](/configuration). When a page is mapped to a different site route, use its absolutehttps://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,summaryandread_when. Developer pages addaudience: developer. - After editing docs, run
pnpm check:docs(format, docs lint and the link audit).pnpm docs:listlists docs for a quick sanity check. - When code, a README or a skill links to
https://docs.wednesdayai.dev, runpnpm docs:check-site-links. It needs network access. It checks every such link the repo emits against the live site’ssitemap.xmland 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 adocs site link gapsissue. A route that fails only because the page is not synced yet clears oncescripts/docs-sync.shpublishes 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.shrebuilds it from one coremainSHA after every core merge.vA.B/directories pin older release minors, newest first.
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-mdxcompiles 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-linksresolves 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.
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.yamlat 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:
- A cheap deterministic gate,
scripts/docs-surface-check.mjs, runs locally before a PR (the coredocs-surface.ymlworkflow is archived; ADR 2399).node scripts/docs-surface-check.mjs --mode=sourcechecks that eachsourcepath still exists.--mode=pages --docs-root=<docs checkout>(docs CI) checks that eachdocs_page, plus optional#anchor, resolves. - A periodic deep audit (
/wai:surface-audit, plugin-owned) enumerates real surfaces and finds new undocumented ones the cheap gate cannot see.
- A cheap deterministic gate,
- Advisory only: branch protection is unavailable on the free-plan private repo, so the check never hard-fails a merge. It exits
0and 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
idso it is idempotent: a GitHub issue (labeldocs-coverage) and/or a/wailedger item. Entries withcoverage: gaporwrongcarry the known-bad baseline until a docs PR flips them todocumented.
Link strategy
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.