This playbook directs AI agents working in the RustFS documentation repository so that every deliverable stays accurate, auditable, and easy to maintain.
Every agent: the operating playbook for writing and reviewing these docs is the skill at
.agents/skills/rustfs-docs/SKILL.md— factual-accuracy discipline, canonical constants, FumaPress syntax, screenshots, and thenpm run docs:check/npm run buildpre-flight. Read it before changing anything undercontent/. For translations, locale structure, language UI, or internationalized routing, also read.agents/skills/localize-rustfs-docs/SKILL.md. It requires product-context translation instead of literal substitution and defines the RustFS terminology workflow. Skills use the cross-client.agents/skills/convention; Claude Code auto-loads them through matching.claude/skills/symlinks, and other agents should open the files directly. See alsoSTYLE.mdfor the detailed style guide.
- Framework: FumaPress (static-site generator powered by Waku + Fumadocs). Content lives in
content/; site configuration is inpress.config.tsx,source.config.ts, andvite.config.ts. - Goal: produce documentation for a distributed object storage product aimed at a global audience, currently English-first with room for other locales.
- Navigation:
content/meta.json(root sidebar: section order, labels, links) and per-foldercontent/**/meta.json(nested group titles/order) define the site structure. New pages must be reflected there immediately. - Routing: a page's URL mirrors its path under
content/(e.g.content/administration/data/bucket/creation.md→/administration/data/bucket/creation)..mdlinks between pages are resolved automatically; you can write./sibling.mdor/absolute/path.
- Accuracy: Data, APIs, and commands must be reproducible; cite third-party information with a concise source note.
- Consistency: Match the existing file layout, naming, frontmatter, and heading hierarchy.
- Minimal change: Touch only files relevant to the task; avoid drive-by formatting or reordering.
- Readability: Use concise active-voice English; spell out technical terms once with their abbreviations (e.g., Large Language Model, LLM).
- Security: Never commit secrets, tokens, or real certificates; scrub sensitive values from sample configs.
git checkout main && git pullto sync with the latest baseline.- Use Node.js 24+. Install dependencies via
npm installwhenever the repo is fresh or packages changed. - Create a topic branch for the task:
git checkout -b docs/<topic>-<short-desc>.
- Locate or create the Markdown file under
content/; when adding a section, createindex.mdin that directory as its entry point. - Every page needs frontmatter with a
title(required — it is rendered as the page heading and the sidebar/tab label) and, ideally, adescription. Do not add a duplicate top-level#heading matching the title; FumaPress renders the title from frontmatter. - Store images in a sibling
images/folder and reference them via relative paths such as./images/<name>.png. FumaPress bundles and optimizes them at build time. Global assets (favicons, logo, manifest) live inpublic/. - Math renders via KaTeX (
$…$inline,$$…$$display). Diagrams render via Mermaid (```mermaidcode blocks). - Rich formatting — use these built-ins (sparingly, where they genuinely aid scanning):
- Admonitions (works in
.md)::::note/:::tip/:::warning[Optional Title]/:::danger… closed by:::. Prefer these over bare>blockquotes for notes and warnings. - Code blocks: language hint required; add
title="/etc/default/rustfs"for file contents,{2,3}meta ranges or[!code highlight]for line highlighting. Put command output in separate```textblocks. - Steps: numbered
## 1. Xxxheadings render automatically as steps (remark-steps) — use for install/how-to sequences. - JSX components require the
.mdxextension (in plain.mdthey are silently dropped):<Cards>/<Card title href>for landing-page link grids,<Tabs items={[...]}><Tab value id>for mutually-exclusive alternatives (eachTabneeds a page-uniqueid; selecting updates the URL hash). Rename a page to.mdxonly when it actually uses components — the URL does not change.
- Admonitions (works in
- Update navigation by editing
content/meta.json(and the relevant foldermeta.json). Sidebar labels come from a page's frontmattertitle, a foldermeta.jsontitle, or a[Custom Label](/url)entry in apagesarray.
- Run the local dev server (
npm run dev) and confirm the changed pages render, links resolve, and the sidebar looks correct. - Compare against requirements or issues to confirm every acceptance criterion is satisfied.
- Run the commands listed in Section 5 to ensure the build succeeds.
- Structure: Start with context, then cover “Overview → Steps → References/Constraints.”
- Terminology: Bold or code-style the first mention of product/module names; wrap commands and filenames in backticks.
- Code blocks: Include language hints (
```bash,```rust, etc.) and provide runnable snippets only. - Tables and media: Tables need a header row; every image requires meaningful
alttext. - Update note: Optionally append “Last Updated: YYYY-MM-DD” at the end for traceability.
- Build: Run
npm run buildto ensure FumaPress generates the static site (output indist/public/) without errors. - Preview (optional):
npm run devis recommended when navigation or interactive pieces change. - Types (optional):
npm run types:check. - Self-checklist:
- Frontmatter is complete and valid (
titlepresent). - Every relative path points to an existing file, and new pages appear in
meta.json. - No new build errors were introduced.
- Frontmatter is complete and valid (
- Use
git statusto verify only task-related files changed. - Write semantic commits such as
docs: <scope>orfeat: add xxx guide. - Include in the Pull Request:
- A concise change summary.
- Build/preview commands and their outcomes.
- Links to related issues or requirement docs.
- When translation or locale sync is involved, list the language directories covered.
npm install # install dependencies (Node 24+)
npm run dev # local development preview (http://localhost:3000)
npm run build # generate static site into dist/public/
npm start # serve the production build
npm run types:check # fumadocs-mdx + tsc type check- Avoid PRs that mix unrelated domains (e.g., config refactors plus large wording sweeps).
- Prefer Markdown + Mermaid for diagrams; if an image is required, provide the source or reproduction steps.
- Fix historical doc issues in the same PR only when documented as a “drive-by fix” with rationale.
Following these guidelines keeps AI agent contributions maintainable and ready for future reviews or automation hooks.