chore: fold developer-docs into a Turborepo monorepo (apps/docs, apps/developer-docs, packages/theme)

.github/workflows/ci.yml

@@ -2,39 +2,51 @@ name: CI
 
 on:
   pull_request:
-    types: [opened, synchronize, reopened]
+  push:
+    branches: [master] # seeds the .turbo cache that PR runs restore from
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  check-format:
-    name: Check Formatting
+  format:
+    name: Format (oxfmt)
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
-
       - uses: pnpm/action-setup@v4
-
       - uses: actions/setup-node@v4
         with:
           node-version: 24
           cache: pnpm
-
       - run: pnpm install --frozen-lockfile
-
       - run: pnpm check:format
 
   build:
-    name: Build
+    name: Types + build (turbo)
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@v4
-
       - uses: pnpm/action-setup@v4
-
       - uses: actions/setup-node@v4
         with:
           node-version: 24
           cache: pnpm
-
+      - uses: actions/cache@v4
+        with:
+          path: .turbo
+          key: turbo-${{ runner.os }}-${{ github.sha }}
+          restore-keys: turbo-${{ runner.os }}-
       - run: pnpm install --frozen-lockfile
-
-      - run: pnpm build
+      # Guards against a second copy of vue / vitepress / the base theme sneaking in
+      # (the shared theme package must resolve the same copies as the apps).
+      - run: pnpm dedupe --check
+      # Turborepo Remote Cache is intentionally not wired up here (needs TURBO_TOKEN /
+      # TURBO_TEAM); the local .turbo cache above is enough for two apps.
+      - run: pnpm turbo run check:types build

.gitignore

@@ -1,24 +1,21 @@
 # Dependencies
-/node_modules
+node_modules/
+.pnpm-store/
 
-# Build output
-/build
-.docusaurus
+# Build output and caches (any app)
+**/.vitepress/dist/
+**/.vitepress/cache/
+**/.vitepress/.temp/
+*.timestamp-*.mjs
+.turbo/
+.vercel/
 
-# VitePress
-.vitepress/dist
-.vitepress/cache
-docs/.vitepress/dist
-docs/.vitepress/cache
-
-# Misc
-.DS_Store
+# Local env files (.env.example templates stay tracked)
 .env
 .env.local
-.env.development.local
-.env.test.local
-.env.production.local
+.env.*.local
 
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
+# OS / editor / local tooling
+.DS_Store
+*.log
+.claude/settings.local.json

.oxfmtrc.json

@@ -1,4 +1,9 @@
 {
   "$schema": "./node_modules/oxfmt/configuration_schema.json",
-  "ignorePatterns": []
+  "ignorePatterns": [
+    "pnpm-lock.yaml",
+    "**/.vitepress/cache/**",
+    "**/.vitepress/dist/**",
+    "**/.turbo/**"
+  ]
 }

AGENTS.md

@@ -1,97 +1,110 @@
-# AGENTS.md — Plane Documentation
+# AGENTS.md — Plane documentation monorepo
 
-## Project overview
+Guidance for AI coding agents (Claude Code, Codex, Cursor, …) working in this repository. `CLAUDE.md` is a
+symlink to this file. Each app has its own `AGENTS.md` with content conventions — **read the app's file before
+editing content there** (`apps/docs/AGENTS.md`, `apps/developer-docs/AGENTS.md`).
 
-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.
+## What this repo is
+
+pnpm workspace + Turborepo holding both Plane documentation sites and their shared theme:
+
+| Package                 | Path                  | What                                                                                                                                            |
+| ----------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@plane/docs`           | `apps/docs`           | [docs.plane.so](https://docs.plane.so) — product documentation                                                                                  |
+| `@plane/developer-docs` | `apps/developer-docs` | [developers.plane.so](https://developers.plane.so) — API reference, self-hosting, dev tools                                                     |
+| `@plane/docs-theme`     | `packages/theme`      | Shared VitePress theme (tokens, fonts, header, layout, Card/CardGroup/Tags, Copy page menu, cookie consent) — consumed as source, no build step |
 
 ## Stack
 
-| Tool            | Version/Notes   |
-| --------------- | --------------- |
-| Framework       | VitePress 1.6.3 |
-| Package manager | pnpm 11.8.0     |
-| Node            | >=24.0.0        |
-| Formatting      | oxfmt           |
-| Styling         | Tailwind CSS v4 |
+| Tool            | Version / notes                                                              |
+| --------------- | ---------------------------------------------------------------------------- |
+| Framework       | VitePress 2.0.0-alpha.16 (pinned in the `catalog:` of `pnpm-workspace.yaml`) |
+| Base theme      | `@voidzero-dev/vitepress-theme` 4.8.x (brings Tailwind CSS v4)               |
+| Package manager | pnpm 11.8.0 (`packageManager` in root `package.json`)                        |
+| Node            | >=24.0.0                                                                     |
+| Task runner     | Turborepo 2.x (`turbo.json`)                                                 |
+| Formatting      | oxfmt (root `.oxfmtrc.json`, defaults: printWidth 100, trailing commas)      |
+| Type-checking   | `tsc` per package, all extending root `tsconfig.base.json`                   |
 
-## Common commands
+## Common commands (run from the repo root)
 
 ```bash
-pnpm dev            # Start local dev server (http://localhost:5173)
-pnpm build          # Build static output into docs/.vitepress/dist
-pnpm preview        # Preview the production build locally
-pnpm fix:format     # Auto-format all files with oxfmt
-pnpm check:format   # Check formatting without writing
+pnpm install                 # one lockfile for the whole workspace
+pnpm dev:docs                # docs.plane.so dev server        → http://localhost:5173
+pnpm dev:developer-docs      # developers.plane.so dev server  → http://localhost:5174
+pnpm dev                     # both, in the Turborepo TUI
+pnpm build                   # turbo run build (apps/<app>/docs/.vitepress/dist)
+pnpm preview                 # turbo run preview (:4173 / :4174)
+pnpm check:types             # turbo run check:types (theme + both apps)
+pnpm check:format            # oxfmt --check .
+pnpm fix:format              # oxfmt --write .
+pnpm check                   # check:format + check:types
+pnpm --filter @plane/docs <script>   # run a script in one package (or cd into the app)
 ```
 
+Turbo runs tasks with `cwd` = the package directory, so per-app `.env` files live at `apps/<app>/.env`
+(templates: `apps/<app>/.env.example`).
+
 ## Repo structure
 
 ```text
-docs/                          # All content and VitePress config
-  .vitepress/
-    config.ts                  # VitePress config — nav, sidebar, search, head tags
-    theme/                     # Custom theme overrides
-  index.md                     # Home page (hero layout)
-  introduction/                # Quickstart, tutorials, core-concepts overview
-  core-concepts/               # Issues, projects, workspaces, pages, cycles, modules
-  integrations/                # GitHub, GitLab, Slack, Sentry, draw.io
-  importers/                   # Jira, Asana, Linear, ClickUp, CSV, Notion
-  authentication/              # SSO, group sync
-  automations/                 # Custom automations
-  workflows-and-approvals/     # Workflows
-  workspaces-and-users/        # Billing, seats, licenses, navigation
-  ai/                          # Plane AI features
-  support/                     # Keyboard shortcuts, get help
-  templates/                   # Page, project, work-item templates
-CONTRIBUTING.md
-README.md
-package.json
+apps/
+  docs/                        # docs.plane.so — see apps/docs/AGENTS.md
+    docs/                      #   content (*.md) + .vitepress/{config.ts, theme/index.ts, theme/site.css}
+    package.json vercel.json tsconfig.json .env.example
+  developer-docs/              # developers.plane.so — see apps/developer-docs/AGENTS.md
+    docs/                      #   content + public/ (images, fonts, logos) + .vitepress/{config.mts, theme/…}
+    package.json vercel.json tsconfig.json .env.example
+packages/
+  theme/                       # @plane/docs-theme — see packages/theme/README.md
+    src/{index.ts, options.ts, components/, layout/, css/, types/}
+turbo.json                     # tasks: build, dev, preview, check:types
+pnpm-workspace.yaml            # workspace packages, dependency catalog, overrides, allowBuilds
+tsconfig.base.json             # shared compilerOptions + @vp-* path aliases (${configDir}-relative)
+.oxfmtrc.json .gitignore .github/workflows/ci.yml
 ```
 
-## Content conventions
-
-- All content files are Markdown (`.md`). Use GitHub-flavored Markdown.
-
-- Each file should have a front matter block at minimum with `title`:
-
-  ```yaml
-  ---
-  title: Page Title
-  description: One-sentence summary (used for SEO meta and og:description)
-  ---
-  ```
-
-- 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.
-
-- Use relative links between docs (e.g., `[Cycles](/core-concepts/cycles)`). Do not use `.md` extensions in links.
-
-- Images are hosted externally at `https://media.docs.plane.so/`. Do not commit binary assets. Reference them directly in Markdown.
-
-- Use the `tabs` plugin (`vitepress-plugin-tabs`) for multi-tab code blocks where appropriate.
-
-## Navigation and sidebar
-
-The sidebar and top nav are configured entirely in `docs/.vitepress/config.ts`. When you add a new page:
-
-1. Create the `.md` file in the appropriate `docs/` subdirectory.
-2. Add an entry to the relevant sidebar section in `config.ts`.
-3. If it needs a top-nav link, add it to `themeConfig.nav`.
+## Rules of the monorepo
+
+- **Theme changes go in `packages/theme`** — both sites pick them up. Never fork a shared component or CSS
+  rule into one app; site-specific bits go through `createPlaneTheme({ brand, components, setup })` options in
+  `apps/<app>/docs/.vitepress/theme/index.ts` or into that app's `site.css`.
+- `packages/theme/src/index.ts` is the only importer of the theme CSS (Tailwind root). Do not import
+  `@plane/docs-theme`'s CSS from an app.
+- Shared dependency versions live in the `catalog:` in `pnpm-workspace.yaml`; apps and the theme reference
+  them as `"catalog:"`. Add new shared deps there. There must be exactly one copy of `vue`, `vitepress` and
+  `@voidzero-dev/vitepress-theme` (`pnpm dedupe --check` runs in CI).
+- One `pnpm-lock.yaml` at the root; never edit it by hand.
+- Each app keeps its own `vercel.json` (redirects, headers, `Accept: text/markdown` rewrite) — Vercel projects
+  point at `apps/docs` and `apps/developer-docs` as Root Directory.
+- Header buttons come from `themeConfig.nav` items flagged `planeButton: "primary" | "secondary"`.
 
 ## Formatting
 
 Run `pnpm fix:format` before committing. CI checks formatting via `pnpm check:format`. Never skip this step.
 
 ## Branches and PRs
 
-- Default/main branch: `master`
-- Open PRs targeting `master`.
-- Branch naming: use short descriptive slugs (e.g., `fix/csv-importer-typo`, `docs/add-milestones-page`).
-- Commit messages: `<type>: short description` — link to an issue where applicable (e.g., `docs: add recurring work items page (#412)`).
+- Default branch: `master`. Open PRs against `master`.
+- Branch naming: short descriptive slugs (`fix/csv-importer-typo`, `docs/add-milestones-page`,
+  `theme/card-hover`).
+- Commit messages: `<type>(<scope>): short description` — scope is optional (`docs`, `developer-docs`,
+  `theme`); link an issue where applicable (`docs: add recurring work items page (#412)`).
+- CI (`.github/workflows/ci.yml`): oxfmt check; `pnpm dedupe --check`; `turbo run check:types build`.
+
+## History note
+
+`apps/developer-docs` was imported from the former `makeplane/developer-docs` repository with full history
+(rename commit + merge). Use `git log --follow <path>`; add `--first-parent` to stay on the docs.plane.so
+lineage for paths that existed in both repos (e.g. `docs/index.md`).
 
 ## What NOT to do
 
-- Do not commit image or font binaries. Use the external CDN.
+- Do not commit new image or font binaries to `apps/docs` (CDN only). `apps/developer-docs/docs/public/`
+  holds its images/logos.
 - Do not modify `pnpm-lock.yaml` manually — let pnpm manage it.
-- Do not edit generated files in `docs/.vitepress/dist/`.
-- Do not add analytics keys, API keys, or secrets to any file. Use environment variables (`.env` locally, platform env vars in CI).
-- Do not rewrite VitePress config structure without understanding the existing sidebar/nav shape — the sidebar is hand-curated and order matters.
+- Do not edit generated files in `**/.vitepress/dist/`.
+- Do not add analytics keys, API keys, or secrets to any file. Use environment variables (`apps/<app>/.env`
+  locally, platform env vars in CI/Vercel).
+- Do not rewrite VitePress config structure without understanding the existing sidebar/nav shape — the
+  sidebars are hand-curated and order matters.