Imported from cncf/contribute-site (AGENTS.md). Install upstream with npx skills add cncf/contribute-site. Copyright stays with the author.

AGENTS.md

Agent orientation for cncf/contribute-site — Docusaurus 3.8 site (React 19, JS config) serving contribute.cncf.io. Docs are routed to the site root (routeBasePath: '/'). Deployed on Netlify.

Commands

npm install                # install dependencies (Node 20+ required)
npm start                  # dev server at http://localhost:3000
npm run build              # production build — the verification gate (see below)
npm run typecheck          # tsc
npm run fix:format         # Prettier (auto-fix)
npm run check:format       # Prettier (check only)

Devcontainer: use npm start -- --host 0.0.0.0 --port 3000 --poll 10000.

Verification gate: there is no PR build/test CI — the only workflows are nightly AI agentic link-checker jobs. Always run npm run build locally before opening a PR. Do not rely on npm test or npm run check to verify changes.

TechDocs sync — top gotcha

docs/techdocs/ is generated and gitignored. It is synced from cncf/techdocs by scripts/sync-techdocs-docs.sh.

• prestart and prebuild hooks auto-sync only when the directory is absent. The first run clones the upstream repo and may be slow.
• Force a re-sync at any time: npm run sync:techdocs.
• Never hand-edit files under docs/techdocs/ — they are wiped on every re-sync. Edits to that content belong in cncf/techdocs. The editUrl in docusaurus.config.js already routes techdocs/** links upstream.
• docs/techdocs/analyses/ is synced from techdocs/analyses/ (top-level in the upstream repo, not under docs/). scripts/normalize_analyses_links.py fixes relative links after the copy.

Content layout

Sidebars are autogenerated from directory names (sidebars.js):

• **/README.md files are excluded from rendering (.docusaurusignore + config).
• Author plain Markdown, not MDX — the site configuration should stay vanilla.
• onBrokenLinks and onBrokenMarkdownLinks are set to warn, so broken internal links do not fail the build. Verify links manually before submitting a PR.

Blog

• Files: blog/YYYY-MM-DD-slug.md
• Required frontmatter: title, date, authors (array of keys), tags (array).
• Add a <!-- truncate --> marker after the excerpt paragraph.
• Every key in authors: must exist in blog/authors.yml, keyed by GitHub handle. New blog submitters should be added to authors.yml using their GitHub profile data. Posts originate from .github/ISSUE_TEMPLATE/blog-post.yml.
• When generating a blog post from an issue, only create the blog post file — do not modify any other files.

Conventions

• Prettier: proseWrap: always, singleQuote: true (defined in package.json).
• CODEOWNERS: TAG-owned directories (docs/community/tags/*, docs/projects/best-practices/security) and CNCF-staff paths (src/, blog/, docs/events/, docs/resources/, config files) require specific team approval. Expect required reviews when touching those paths.
• netlify.toml preview builds run npm run build:preview; production runs npm run build:production — both call sync:techdocs first.

Agent boundaries

Agents are expected to fix markdown links, formatting, spelling, etc. Agents must never editorialize or edit content, as that is strictly the operator's domain.

Content, style, and report authoring

For content rules, style guide, health-check report templates, maturity-level conventions, and blog/issue workflows, see .github/copilot-instructions.md — do not duplicate those rules here.