|
| 1 | +# Arcade Docs |
| 2 | + |
| 3 | +Arcade documentation site built with Next.js + Nextra (App Router), using pnpm as the package manager. Content is authored in MDX with custom React components. Check `package.json` for current framework versions. |
| 4 | + |
| 5 | +## Commands |
| 6 | + |
| 7 | +```bash |
| 8 | +pnpm dev # Local dev server (port 3000) |
| 9 | +pnpm build # Full production build (toolkit-markdown → next build → pagefind) |
| 10 | +pnpm lint # Lint with Ultracite (Biome-based) |
| 11 | +pnpm format # Auto-format with Ultracite |
| 12 | +pnpm test # Run all Vitest tests |
| 13 | +pnpm test:watch # Watch mode |
| 14 | +pnpm vale:check # Check docs against style rules |
| 15 | +``` |
| 16 | + |
| 17 | +Run a single test: |
| 18 | +```bash |
| 19 | +pnpm vitest run tests/broken-link-check.test.ts |
| 20 | +``` |
| 21 | + |
| 22 | +## Architecture |
| 23 | + |
| 24 | +- **`app/en/`** — English docs content (MDX pages). Nextra file-based routing with `_meta.tsx` for navigation order. i18n handled via `middleware.ts`. |
| 25 | +- **`app/_components/`** — Shared React components (tabbed code blocks, toolkit docs, callouts, etc.). |
| 26 | +- **`app/_lib/`** — Data-fetching utilities (toolkit catalog, slug generation, static params). |
| 27 | +- **`app/api/`** — API routes (markdown export, toolkit-data, glossary). |
| 28 | +- **`toolkit-docs-generator/`** — Generates MCP toolkit documentation from server metadata JSON files in `toolkit-docs-generator/data/toolkits/`. |
| 29 | +- **`scripts/`** — Build/CI scripts (clean markdown export, Vale style fixes, redirect checking, pagefind indexing, i18n sync). |
| 30 | +- **`tests/`** — Vitest tests (broken links, internal link validation, sitemap, smoke tests). |
| 31 | +- **`lib/`** — Next.js utilities (glossary remark plugin, llmstxt plugin). |
| 32 | +- **`next.config.ts`** — Contains ~138 redirect rules. |
| 33 | + |
| 34 | +## Content Authoring |
| 35 | + |
| 36 | +Follow **STYLEGUIDE.md** for writing standards and **AUTHORING.md** for formatting conventions. Key points: |
| 37 | + |
| 38 | +- Sentence case for headings. Active voice. Direct tone. |
| 39 | +- Product is always "Arcade" (never abbreviated, never "Arcade AI"). |
| 40 | +- Use "Arcade Engine" (capitalized), "MCP server" (lowercase server), "tool" (lowercase), "auth provider". |
| 41 | +- Code snippets: 4 spaces for Python, 2 spaces for other languages. |
| 42 | +- Run `pnpm vale:check` before submitting docs changes. |
| 43 | + |
| 44 | +## Pre-commit Hooks |
| 45 | + |
| 46 | +Husky runs on commit: Vale style checks on `.md/.mdx`, `_meta.tsx` key validation, redirect checking for deleted/renamed pages, internal link updates, and Ultracite formatting. You MUST fix any issues surfaced by the pre-commit hooks. NEVER bypass hooks with `--no-verify` or similar flags. |
| 47 | + |
| 48 | +## Key Config Files |
| 49 | + |
| 50 | +- `biome.jsonc` — Linter/formatter rules (Biome via Ultracite) |
| 51 | +- `.vale.ini` — Vale style checker config (Google style base + Arcade vocabulary) |
| 52 | +- `.nvmrc` — Required Node version |
| 53 | +- `tsconfig.json` — TypeScript compiler configuration |
| 54 | +- `components.json` — shadcn/ui component config |
| 55 | +- `postcss.config.mjs` — PostCSS/Tailwind config |
| 56 | + |
| 57 | +## Code Quality |
| 58 | + |
| 59 | +NEVER add suppression comments (`// @ts-ignore`, `// @ts-expect-error`, `// biome-ignore`, `eslint-disable`, `{/* prettier-ignore */}`, etc.) to bypass TypeScript or linter errors. Fix the underlying issue instead. |
0 commit comments