Volcano Developer Docs

Assembly point and format contract for the Volcano developer documentation site. Content is authored in each product repo and pulled in here by CI; this repo owns the shared structure, the markdown format contract, and the cross-surface intro pages.

How it works

source repos (own their docs, follow the contract)
        │  daily sync — a per-repo subtree copy into content/<section>/,
        │  committed by the bot (manual escape hatch available)
        ▼
volcano-docs (this repo: contract + assembly + get-started + synced content)
        │  build — Hugo / Docusaurus / Starlight / Next.js in volcano-web (TBD)
        ▼
developer docs site

Sync is designed to run on a daily schedule rather than on every merge to main, to keep commit noise low — but the schedule is currently paused (until the source repos land on their default branches), so the active trigger today is a manual run of the Sync docs workflow (workflow_dispatch), optionally scoped to a single section via the source input. Each run opens a PR that auto-merges. Source repos are internal, so the job authenticates as the Volcano GitHub App. See .github/workflows/sync-docs.yml.

The serving layer is intentionally not decided yet. The markdown format (spec/markdown-format.md) uses neutral frontmatter fields so any generator can consume it with a thin adapter — the choice between a standalone static site and a route inside volcano-web stays open.

Section → source repo

Section	Source repo	Path	Owns
content/get-started/	this repo	—	Cross-surface intro
content/platform/	Kong/volcano-hosting	docs/public/	Platform concepts + API reference
content/sdk/index.md	this repo	—	SDK language selector and runtime requirements
content/sdk/js/	Kong/volcano-sdk-js	docs/	JavaScript/TypeScript SDK
content/sdk/python/	Kong/volcano-sdk-python	docs/	Python SDK
content/sdk/ruby/	Kong/volcano-sdk-ruby	docs/	Ruby SDK
content/cli/	Kong/volcano-cli	docs/	CLI reference

Agent skills (volcano-skills) and IDE plugins (volcano-agentic-plugins) are not synced here — they are agent instruction files, not human docs. A human-facing "AI / IDE integrations" section, if wanted, is curated content.

The mapping is defined machine-readably in docs.config.yaml.

Editing docs

• Product docs (platform, SDK languages, CLI): edit them in their source repo, following spec/markdown-format.md. The sync bot commits them here — do not hand-edit content/platform, content/sdk/js, content/sdk/python, content/sdk/ruby, or content/cli; they are overwritten on every sync.
• Intro pages: edit content/get-started/ here.
• SDK landing page: edit content/sdk/index.md here when a language's runtime requirements or shared capabilities change. Check the claims against its package metadata and keep the sync destinations scoped to the language subdirectories.

Rollout

1. Land the format contract + sync job + tooling (this repo). ← we are here
2. In each source repo: run scripts/migrate-docs.mjs to reformat docs/, add the spec/ci-caller.example.yml lint workflow, and paste spec/AGENTS.snippet.md into the repo's AGENTS.md.
3. Install the Volcano GitHub App on volcano-docs and every source repo, and set the VOLCANO_APP_ID variable + VOLCANO_APP_KEY secret.
4. Pick and wire the generator.

Site (Fumadocs)

The site is a Fumadocs app that reads the assembled content/ tree. Stack and conventions mirror volcano-web: pnpm, Node 24, Tailwind v4, App Router with src/, ESLint flat config, and Conventional Commits.

make install
make dev      # http://localhost:3030  (override: make dev PORT=5000)
make build    # production build (also regenerates .source)
make lint     # eslint
make check    # lint + build (pre-PR)
make          # list all targets

Structure:

• src/app — App Router (layout.tsx, (docs) group, [[...slug]] renderer, api/search).
• src/lib/source.ts — Fumadocs loader over content/ (mounted at /).
• source.config.ts — Fumadocs MDX config; .source/ is generated (gitignored).
• Custom branding/UI is intentionally deferred — this is the default theme.

Version note: Fumadocs 16 hard-requires Next 16, so the site is on Next 16 + React 19.2 rather than volcano-web's Next 15.5. Every other convention matches.

Tooling

• scripts/lint-docs.mjs — validates docs against the contract; run by every source repo via the reusable .github/workflows/lint-docs.yml.
• scripts/migrate-docs.mjs — one-time reformat of a repo's docs/ (frontmatter, H1 removal, fence languages). Seeds are for review.