|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is the **Plane product documentation site** ([docs.plane.so](https://docs.plane.so)), built with VitePress. It was recently migrated from Docusaurus — the old `sidebars.ts` is a legacy artifact and is no longer used. |
| 8 | + |
| 9 | +## Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +pnpm dev # Start local dev server |
| 13 | +pnpm build # Production build (outputs to docs/.vitepress/dist/) |
| 14 | +pnpm preview # Preview production build locally |
| 15 | +pnpm format # Format all files with oxfmt |
| 16 | +pnpm format:check # Validate formatting (runs in CI) |
| 17 | +``` |
| 18 | + |
| 19 | +## Architecture |
| 20 | + |
| 21 | +### Directory Layout |
| 22 | + |
| 23 | +- `docs/` — all documentation content as Markdown files |
| 24 | +- `docs/.vitepress/config.mts` — main VitePress config: sidebar navigation, head tags, analytics, theme settings |
| 25 | +- `docs/.vitepress/theme/` — custom theme layer extending VitePress default theme |
| 26 | +- `docs/.vitepress/theme/index.ts` — theme entry: registers custom components and tabs plugin |
| 27 | +- `docs/.vitepress/theme/style.css` — global CSS (Tailwind v4, custom properties, component styles) |
| 28 | +- `docs/.vitepress/theme/components/` — custom Vue components used in Markdown |
| 29 | +- `docs/public/` — static assets (fonts, logos) |
| 30 | +- `vercel.json` — 200+ URL redirects for backward compatibility with old Docusaurus paths |
| 31 | +- `sidebars.ts` — **legacy file from Docusaurus migration, not used by VitePress** |
| 32 | + |
| 33 | +### Sidebar Navigation |
| 34 | + |
| 35 | +The sidebar is defined entirely in `docs/.vitepress/config.mts` under `themeConfig.sidebar`. When adding or reorganizing pages, edit this array directly. |
| 36 | + |
| 37 | +### Custom Vue Components |
| 38 | + |
| 39 | +These are globally registered and can be used directly in any Markdown file: |
| 40 | + |
| 41 | +- **`<Card>`** — content card with optional icon and link. Has built-in SVG icons for GitHub, Slack, GitLab, Sentry, Linear, Asana, Jira, CSV. |
| 42 | +- **`<CardGroup>`** — responsive grid wrapper. Prop: `cols` (default 2). |
| 43 | +- **`<Tags>`** — pricing tier badges (Pro, Business, Enterprise). Accepts `:tags` array with `name`, `link`, and `additionalClass` (`pro`, `business`, `enterprise`). |
| 44 | + |
| 45 | +### Markdown Conventions |
| 46 | + |
| 47 | +```markdown |
| 48 | +<!-- Pricing tags --> |
| 49 | +<Tags :tags='[{ name: "Pro", link: "/url", additionalClass: "pro" }]' /> |
| 50 | + |
| 51 | +<!-- Card groups --> |
| 52 | +<CardGroup :cols="2"> |
| 53 | + <Card title="Title" icon="github" href="/path"> |
| 54 | + Description |
| 55 | + </Card> |
| 56 | +</CardGroup> |
| 57 | + |
| 58 | +<!-- Admonitions --> |
| 59 | +::: tip |
| 60 | +::: warning |
| 61 | +::: danger |
| 62 | + |
| 63 | +<!-- Tabs (via vitepress-plugin-tabs) --> |
| 64 | +:::tabs |
| 65 | +== Tab 1 |
| 66 | +Content |
| 67 | +== Tab 2 |
| 68 | +Content |
| 69 | +::: |
| 70 | + |
| 71 | +<!-- Image styling via hash fragments --> |
| 72 | + <!-- rounded corners + shadow --> |
| 73 | + <!-- top-left corner only --> |
| 74 | +``` |
| 75 | + |
| 76 | +### Image Hosting |
| 77 | + |
| 78 | +All documentation images are hosted externally at `https://media.docs.plane.so/`. Reference them by full URL in Markdown. |
| 79 | + |
| 80 | +## CI |
| 81 | + |
| 82 | +GitHub Actions (`.github/workflows/build.yml`) runs two jobs on PRs and pushes to `master`: |
| 83 | +1. **format** — `pnpm format:check` |
| 84 | +2. **build** — `pnpm build` |
| 85 | + |
| 86 | +## Formatting |
| 87 | + |
| 88 | +Uses oxfmt (`.oxfmtrc.json`): 120 char width, 2-space indent, ES5 trailing commas. |
0 commit comments