|
| 1 | +# AGENTS.md — Plane Documentation |
| 2 | + |
| 3 | +## Project overview |
| 4 | + |
| 5 | +This is the [Plane](https://plane.so) product documentation site, built with [VitePress v1.6.3](https://vitepress.dev/) and hosted at [docs.plane.so](https://docs.plane.so). All content lives in the `docs/` directory as Markdown files. |
| 6 | + |
| 7 | +## Stack |
| 8 | + |
| 9 | +| Tool | Version/Notes | |
| 10 | +| --------------- | --------------- | |
| 11 | +| Framework | VitePress 1.6.3 | |
| 12 | +| Package manager | pnpm 10 | |
| 13 | +| Node | >=24.0.0 | |
| 14 | +| Formatting | oxfmt | |
| 15 | +| Styling | Tailwind CSS v4 | |
| 16 | + |
| 17 | +## Common commands |
| 18 | + |
| 19 | +```bash |
| 20 | +pnpm dev # Start local dev server (http://localhost:5173) |
| 21 | +pnpm build # Build static output into docs/.vitepress/dist |
| 22 | +pnpm preview # Preview the production build locally |
| 23 | +pnpm fix:format # Auto-format all files with oxfmt |
| 24 | +pnpm check:format # Check formatting without writing |
| 25 | +``` |
| 26 | + |
| 27 | +## Repo structure |
| 28 | + |
| 29 | +```text |
| 30 | +docs/ # All content and VitePress config |
| 31 | + .vitepress/ |
| 32 | + config.ts # VitePress config — nav, sidebar, search, head tags |
| 33 | + theme/ # Custom theme overrides |
| 34 | + index.md # Home page (hero layout) |
| 35 | + introduction/ # Quickstart, tutorials, core-concepts overview |
| 36 | + core-concepts/ # Issues, projects, workspaces, pages, cycles, modules |
| 37 | + integrations/ # GitHub, GitLab, Slack, Sentry, draw.io |
| 38 | + importers/ # Jira, Asana, Linear, ClickUp, CSV, Notion |
| 39 | + authentication/ # SSO, group sync |
| 40 | + automations/ # Custom automations |
| 41 | + workflows-and-approvals/ # Workflows |
| 42 | + workspaces-and-users/ # Billing, seats, licenses, navigation |
| 43 | + ai/ # Plane AI features |
| 44 | + support/ # Keyboard shortcuts, get help |
| 45 | + templates/ # Page, project, work-item templates |
| 46 | +CONTRIBUTING.md |
| 47 | +README.md |
| 48 | +package.json |
| 49 | +``` |
| 50 | + |
| 51 | +## Content conventions |
| 52 | + |
| 53 | +- All content files are Markdown (`.md`). Use GitHub-flavored Markdown. |
| 54 | + |
| 55 | +- Each file should have a front matter block at minimum with `title`: |
| 56 | + |
| 57 | + ```yaml |
| 58 | + --- |
| 59 | + title: Page Title |
| 60 | + description: One-sentence summary (used for SEO meta and og:description) |
| 61 | + --- |
| 62 | + ``` |
| 63 | + |
| 64 | +- Page headings (`#`) must match the sidebar label defined in `docs/.vitepress/config.ts`. When renaming a page, update both the file heading and the sidebar entry. |
| 65 | + |
| 66 | +- Use relative links between docs (e.g., `[Cycles](/core-concepts/cycles)`). Do not use `.md` extensions in links. |
| 67 | + |
| 68 | +- Images are hosted externally at `https://media.docs.plane.so/`. Do not commit binary assets. Reference them directly in Markdown. |
| 69 | + |
| 70 | +- Use the `tabs` plugin (`vitepress-plugin-tabs`) for multi-tab code blocks where appropriate. |
| 71 | + |
| 72 | +## Navigation and sidebar |
| 73 | + |
| 74 | +The sidebar and top nav are configured entirely in `docs/.vitepress/config.ts`. When you add a new page: |
| 75 | + |
| 76 | +1. Create the `.md` file in the appropriate `docs/` subdirectory. |
| 77 | +2. Add an entry to the relevant sidebar section in `config.ts`. |
| 78 | +3. If it needs a top-nav link, add it to `themeConfig.nav`. |
| 79 | + |
| 80 | +## Formatting |
| 81 | + |
| 82 | +Run `pnpm fix:format` before committing. CI checks formatting via `pnpm check:format`. Never skip this step. |
| 83 | + |
| 84 | +## Branches and PRs |
| 85 | + |
| 86 | +- Default/main branch: `master` |
| 87 | +- Active development and review happens on the `preview` branch — open PRs targeting `preview`, not `master`. |
| 88 | +- Branch naming: use short descriptive slugs (e.g., `fix/csv-importer-typo`, `docs/add-milestones-page`). |
| 89 | +- Commit messages: `<type>: short description` — link to an issue where applicable (e.g., `docs: add recurring work items page (#412)`). |
| 90 | + |
| 91 | +## What NOT to do |
| 92 | + |
| 93 | +- Do not commit image or font binaries. Use the external CDN. |
| 94 | +- Do not modify `pnpm-lock.yaml` manually — let pnpm manage it. |
| 95 | +- Do not edit generated files in `docs/.vitepress/dist/`. |
| 96 | +- Do not add analytics keys, API keys, or secrets to any file. Use environment variables (`.env` locally, platform env vars in CI). |
| 97 | +- Do not rewrite VitePress config structure without understanding the existing sidebar/nav shape — the sidebar is hand-curated and order matters. |
0 commit comments