Contributing
We welcome contributions from everyone — fixing a typo, clarifying a paragraph, adding a missing example, or writing a whole new page. Documentation is a team effort, and small improvements compound.
Before you start
Please skim these — they save back-and-forth in review:
- CONTRIBUTING.md — setup, workflow, and how to submit a PR. Start here.
- STYLE-GUIDE.md — voice, structure, and conventions. How we write.
- WRITING_DOCS.md — deep reference: components, frontmatter, navigation, auto-injection.
Ways to contribute
| If you want to… |
Do this |
| Fix a typo or broken link |
Open a PR directly — small fixes don't need prior discussion |
| Report a mistake or unclear section |
Open an issue with the page URL |
| Request a new guide or cookbook |
Open an issue describing the use case |
| Add a new page |
Read WRITING_DOCS.md, then follow the flow in CONTRIBUTING.md |
| Improve the site itself (styles, components, layout) |
Open an issue first so we can discuss direction |
Contribution workflow
1. Fork the repo (external) or pull the latest `dev` (internal)
2. Create a branch: git checkout -b docs/your-change
3. Make your changes, preview locally with `pnpm dev`
4. Check for broken links: pnpm audit-links
5. Confirm the site builds: pnpm build
6. Push and open a PR against `dev`
7. A maintainer reviews; once approved, changes flow `dev` → `main` → live site
Merging to main triggers an automated deploy to docs.futureagi.com. Please don't push directly to main or dev — always go through a PR.
Quick start (local setup)
Prerequisites: Node.js 18+ and pnpm.
# Clone
git clone https://github.com/future-agi/docs.git
cd docs
# Install
pnpm install
# Run dev server at http://localhost:4321
pnpm dev
Create a new page
The scaffold script creates the MDX file and wires it into the sidebar in one step:
pnpm new-doc docs/evaluation/my-eval "My Custom Eval"
See WRITING_DOCS.md for the full authoring reference — components, navigation, frontmatter, images, and common pitfalls.
Commands
| Command |
What it does |
pnpm dev |
Start dev server with hot reload |
pnpm build |
Production build + Pagefind search index |
pnpm preview |
Serve the production build locally |
pnpm new-doc <path> [title] |
Scaffold a new doc page |
pnpm audit-links |
Check for broken internal links |
Project structure
docs/
├── src/
│ ├── components/docs/ # MDX components (Card, Tip, Tabs, Steps, ...)
│ ├── layouts/ # Page layouts
│ ├── lib/navigation.ts # Sidebar & tab structure
│ ├── pages/docs/ # All doc pages (MDX) — file path maps to URL
│ ├── plugins/ # Vite plugin for auto-layout & auto-imports
│ └── styles/ # Global CSS and design tokens
├── public/images/docs/ # Images, organized by section
├── scripts/ # new-doc scaffold, link audit, etc.
└── .github/workflows/ # Deploy pipeline
Writing rules at a glance
Full details live in STYLE-GUIDE.md. Highlights:
- Voice: clear, direct, second person ("you"). No marketing fluff.
- Headings: start at
## — the <h1> comes from frontmatter title.
- Links: relative paths (
/docs/...), never hardcoded https://docs.futureagi.com.
- Images: place in
public/images/docs/<section>/, reference as /images/docs/....
- Code blocks: always language-tagged (
```python, ```bash).
- Examples over prose: show a working snippet before explaining it.
Branches
| Branch |
Purpose |
main |
Production. Pushes here trigger a deploy. Protected — PR only. |
dev |
Integration. Open PRs against this. Protected — PR only. |
docs/*, fix/*, feat/* |
Feature branches — branch from dev, merge back to dev. |
main_archive, dev_archive |
Frozen snapshots of the pre-Astro docs site (kept for reference). |
Reporting issues
Found something wrong, confusing, or missing? Open an issue and include:
- The page URL (e.g.
https://docs.futureagi.com/docs/evaluation/overview)
- What you expected vs. what the page says
- A suggested fix, if you have one
For security-sensitive issues, please email the team privately instead of opening a public issue.
Getting help
- Product questions: docs.futureagi.com or the in-app chat
- Contribution questions: comment on your draft PR — we'll help
- Anything else: open an issue
Thanks for helping make Future AGI's docs better.