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 UI uses the design tokens in src/app/theme.css alongside Fumadocs primitives.

Docs, Cookbooks, and Blog

The shared header links three sections while preserving existing docs URLs:

• / and the existing guide routes use the documentation sidebar.
• /cookbooks lists recipes; recipe pages use their own sidebar and table of contents.
• /blog lists posts; both the listing and articles share a Blog sidebar with search, All posts, and topic filters with counts.

Author recipes in content/cookbooks/ and posts in content/blog/. Each section's index.md provides its introduction, and meta.json controls the card and navigation order. Keep "..." at the end of each section's meta.json page list so new Markdown pages appear automatically after explicitly ordered pages in the listing and navigation tree, using their frontmatter title and description. Cookbooks uses that tree for its sidebar; Blog keeps its topic filters in the sidebar. All sections share search, sitemap generation, relative Markdown link handling, and the raw Markdown API. Search is scoped to the active section. In Blog, selecting a topic filters both the post cards and search results; All posts clears the filter. Topics and counts are derived from Markdown tags, and selections stay active while navigating between posts.

Blog posts can also include optional metadata:

author: Your name
published: "2026-10-19"
tags: [storage, authentication]

The blog displays these fields when provided and includes them in article metadata. Follow spec/markdown-format.md for the full content contract.

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.