Docs as Code skill for Codex

Docs-as-code is working when docs change in the same pull request as the code they describe, a broken link or invalid page fails CI before merge, reviewers can see a rendered preview, and publishing is a merge rather than a manual upload.

Inspect first

cat AGENTS.md 2>/dev/null | head -80
ls docs website site 2>/dev/null; ls docusaurus.config.* astro.config.* docs.json mint.json mkdocs.yml 2>/dev/null
cat package.json 2>/dev/null | head -40                   # node version, docs scripts
ls .github/workflows; rg -l "docs" .github/workflows 2>/dev/null
ls .vale.ini .markdownlint* 2>/dev/null

If a platform already exists, keep it unless the user asked to migrate. Most “docs site” problems are content and CI problems, not platform problems.

Choose a platform

Situation	Default	Why
Open-source project or product docs, React team, needs versioning and i18n	Docusaurus 3	Built-in versioning, mature plugin ecosystem
Wants fast static site, minimal JS, built-in search, Astro or framework-agnostic team	Astro Starlight	Pagefind search built in, strong defaults, accessible
API-first SaaS wanting hosted docs with API playground and little maintenance	Mintlify	Hosted, docs.json config, OpenAPI pages; paid tiers for some features
Python project already on MkDocs	Stay on MkDocs	mkdocs build --strict gives the CI gate; migration rarely pays off
Internal docs for one service	Markdown in docs/ rendered by the Git host	No site needed until there are ~20+ pages or outside readers

Versioning trade-off: Docusaurus versions by copying the docs folder per version (versioned_docs/version-x/). Starlight has no built-in versioning (community plugins exist). Mintlify versions through navigation.versions in docs.json. If you must keep several majors documented, that difference often decides the platform.

Platform-specific setup, config snippets and gotchas live in references/platforms.md; read it once the platform is chosen.

Workflow

- [ ] 1. Inspect existing docs, platform and CI (commands above)
- [ ] 2. Choose or confirm the platform (table above); confirm with the user before migrating
- [ ] 3. Scaffold or fix config; make the build fail on broken links
- [ ] 4. Add lint: markdownlint-cli2 for structure, Vale for prose
- [ ] 5. Add CI: build + lint on every PR touching docs; preview deployment
- [ ] 6. Add publish job on main (confirm the deploy target with the user)
- [ ] 7. Set versioning policy if the product ships majors
- [ ] 8. Document the docs workflow in AGENTS.md / CONTRIBUTING.md

Scaffolding and installs need network (npm create, npx, pip install). In a Codex sandbox with network off, request approval or prepare the files and leave the install for the user, saying so in the report.

Repository layout

docs/                    # content (Markdown/MDX), one folder per section
  getting-started/
  guides/
  reference/
static/ or public/       # images, downloads
.vale.ini                # prose lint config
styles/                  # Vale styles and project vocabulary
  config/vocabularies/Project/accept.txt
.markdownlint-cli2.jsonc
.github/workflows/docs.yml

• Keep content separate from site code so writers do not touch React or Astro files.
• Images next to the page or in one static/img/<section>/ tree; name them by content (webhook-retry-timeline.png), always with alt text.
• One Markdown file per URL. File and folder names become slugs; renames break links, so add redirects when you move pages.

Lint configuration

# .vale.ini
StylesPath = styles
MinAlertLevel = suggestion
Vocab = Project
Packages = Google, write-good

[*.{md,mdx}]
BasedOnStyles = Vale, Google
Google.Headings = NO          # turn off rules that fight the house style

vale sync                     # downloads packages listed above (network)
vale docs/
npx markdownlint-cli2 "docs/**/*.md"

Add product names, acronyms and code terms to styles/config/vocabularies/Project/accept.txt (one per line, regex allowed) instead of disabling the spelling rule.

CI pipeline (GitHub Actions, Docusaurus or Starlight)

name: docs
on:
  pull_request:
    paths: ['docs/**', 'website/**', 'package.json', '.github/workflows/docs.yml']
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with: { node-version: 22, cache: npm }
      - run: npm ci
      - run: npx markdownlint-cli2 "docs/**/*.md"
      - uses: errata-ai/vale-action@v2
        with: { files: docs }
      - run: npm run build          # fails on broken links when configured to throw
      - uses: actions/upload-pages-artifact@v4
        if: github.ref == 'refs/heads/main'
        with: { path: build }        # Starlight/Astro: dist
  deploy:
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    permissions: { pages: write, id-token: write }
    environment: { name: github-pages, url: '${{ steps.d.outputs.page_url }}' }
    steps:
      - id: d
        uses: actions/deploy-pages@v4

Pin action majors to whatever is current when you write the workflow, and pin by SHA if the repo’s security policy requires it. The deploy job publishes to the public internet: add or change it only after the user confirms the target (GitHub Pages, Netlify, Vercel, Cloudflare Pages) and that the content is meant to be public.

PR previews: Netlify, Vercel and Cloudflare Pages create them per PR through their Git integration; Mintlify generates preview deployments for PRs when the GitHub app is installed. Prefer the host’s integration over custom preview jobs.

Link checking

Layer	Tool	Catches
Internal links during build	Platform setting (onBrokenLinks: 'throw', mkdocs build --strict, starlight-links-validator, mint broken-links)	Moved or renamed pages, bad anchors
External links	lychee on a schedule, not on every PR	Rotted third-party URLs

Run external link checks nightly or weekly; third-party outages should not block merges.

lychee --offline docs/        # local files and anchors only, no network
lychee --max-retries 2 --accept 200,429 docs/   # full check, needs network

Versioning policy

• Version docs only when users run several majors in production. Otherwise one “latest” set plus a changelog is cheaper and less confusing.
• Cut a docs version at release time, never before: npm run docusaurus docs:version 2.0 snapshots the current docs/ into versioned_docs/version-2.0/.
• Fix typos in every maintained version; backport only factual corrections to old ones.
• Drop versions that are out of support and redirect them to the latest.
• Show an “unreleased” banner on the next docs so readers do not use unshipped APIs.

Gotchas

• MDX is JSX: bare <, { and unclosed HTML tags in Markdown break the build. Escape or wrap in code spans.
• Moving or renaming files without redirects breaks inbound links from search engines and other sites. Add redirects in the same PR.
• Generated reference (API, CLI) committed by hand drifts. Generate it in the build or in a CI job that fails when the output differs.
• Versioned docs multiply build time and search noise; each version is a full copy.
• Search indexing (Algolia DocSearch) needs a crawler config; local search plugins are simpler for small sites.
• Making a whole workflow pass by setting link checks to warn. Fix or explicitly exclude the specific link instead.

Verification

• npm run build (or platform equivalent) passes locally and fails when you deliberately break one internal link; revert the break afterwards.
• vale docs/ and markdownlint-cli2 run clean, or remaining alerts are listed.
• CI runs on a test PR and shows a preview link.
• Every page reachable from navigation; no orphans (compare sidebar entries to files).

Report

**Platform:** Astro Starlight (kept existing), Node 22
**Build gate:** starlight-links-validator added; build now fails on 3 broken links, all fixed
**Lint:** Vale (Google + Project vocab, 41 accepted terms), markdownlint-cli2
**CI:** .github/workflows/docs.yml, PR build + lint; deploy job prepared but disabled pending your confirmation of GitHub Pages
**Versioning:** not enabled; single latest docs (one supported major)
**Not run:** vale sync and npm ci (network off in sandbox)