RustFS Documentation

RustFS is an S3-compatible distributed object storage engine written in Rust. This repository hosts the official documentation site, built with FumaPress (a static-site generator powered by Waku and Fumadocs). Use this guide to understand the layout, add or update content, and keep the docs build passing.

Quick Links

• Documentation: https://docs.rustfs.com
• Chinese docs: https://docs.rustfs.com.cn
• Repo issues: https://github.com/rustfs/docs.rustfs.com/issues
• Product issues & roadmap: https://github.com/rustfs/rustfs/issues

Repository Snapshot

• content/<locale>/ – localized Markdown (.md) and MDX (.mdx) sources. URLs mirror the locale and folder path (for example, content/en/installation/linux/quick-start.md → /en/installation/linux/quick-start).
• content/<locale>/meta.json – locale-specific root sidebar definition (section order, labels, and links).
• content/<locale>/**/meta.json – locale-specific sidebar titles and ordering for nested groups.
• press.config.tsx – site config: name, navbar links, social links, logo, analytics, SEO, plugins, and MDX components.
• source.config.ts – content collection + global MDX options (KaTeX math, Mermaid diagrams).
• waku.config.ts – Waku/Vite plugins (FumaPress, Fumadocs MDX, Tailwind).
• src/app.css – Tailwind + Fumadocs UI theme imports.
• src/components/ – custom React components (e.g. the Mermaid renderer).
• public/ – static assets (favicons, logo, manifest) served from the site root.
• Images can be co-located in an images/ folder beside a page and referenced with relative paths (e.g. ./images/diagram.png); FumaPress bundles and optimizes them at build time.

Contribution Paths

Quick edits on GitHub

1. Browse to the page on https://docs.rustfs.com and use the Open → Edit action (or the GitHub edit link).
2. Use the inline editor for small fixes (typos, broken links, formatting).
3. Describe the change briefly, submit a pull request (PR), and link any related issue.

Planned work or new content

1. Open/confirm an issue so others see what you are tackling.
2. Create a topic branch such as docs/feature-short-title.
3. Add or edit Markdown under content/, keeping edits focused.
4. Reflect new pages in content/meta.json (and the relevant folder meta.json) so they appear in the sidebar.

Translations

The site exposes en, zh, de, fr, and ja locale routes. Simplified Chinese is fully localized. German, French, and Japanese currently localize the site UI, homepage, and navigation while using the current English page body as an explicit fallback. Translate fallback pages from content/en, keep each locale's relative file tree aligned, and preserve non-Mermaid technical code blocks exactly.

Run npm run docs:check, npm run types:check, and npm run build before submitting localization changes.

Local Development

Prerequisites

• Node.js 20+ (Node 22 recommended)
• npm
• Git

Setup & common commands

git clone https://github.com/rustfs/docs.rustfs.com.git
cd docs.rustfs.com
npm install

# Work locally
npm run dev        # Waku dev server (defaults to http://localhost:3000)

# Required before opening a PR
npm run build      # static export to dist/public/

# Optional checks
npm start          # serve the production build
npm run types:check

Authoring Guidelines

• Every page needs frontmatter with a title (rendered as the page heading and sidebar/tab label) and ideally a description. Do not repeat the title as a top-level # heading in the body — FumaPress renders the title automatically.
• Follow the structure “context → overview → steps → references” and keep prose concise, active, and reproducible.
• Spell out a term the first time it appears (for example, “Large Language Model (LLM)”).
• Cite third-party facts inline and scrub secrets or private configuration values from examples.
• Use fenced code blocks with language hints (```bash, ```rust) and provide runnable snippets only.
• Math renders via KaTeX using $…$ (inline) and $$…$$ (display). Diagrams render via Mermaid using ```mermaid code blocks.
• When adding assets, include descriptive alt text and ensure tables contain a header row.

See AGENTS.md for the full checklist that governs navigation updates, localization, and release hygiene.

Pull Request Checklist

• npm run build completes without errors.
• content/meta.json (and folder meta.json) updated for any new or renamed pages.
• Frontmatter validated (title present) and relative links confirmed.
• Conventional commit message (for example, docs: add lifecycle guide).
• PR description explains the change, references issues, and includes screenshots when visuals change.

Deployment

main is built by GitHub Actions (.github/workflows/deploy.yml) with npm run build, and the static output in dist/public/ is uploaded to Aliyun OSS.

License

Documentation content is released under the Creative Commons Attribution 4.0 International License. By contributing, you agree that your submissions use the same license.

Last Updated: 2026-07-12