mirror of
https://github.com/netbirdio/docs.git
synced 2026-05-11 03:19:52 +00:00
e22a81509e
* docs: refresh CLAUDE.md for Next.js 16 toolchain and API sidebar - Note Node.js >=20.9 requirement (Next 16 fails the build below this) - Update dev/build descriptions to mention gen:edit-routes; add start and gen:edit-routes to the common commands list - Document the second sidebar file (NavigationAPI.jsx) alongside NavigationDocs.jsx so the API sidebar is discoverable * docs: add Security boundaries section to CLAUDE.md Calls out four posture items relevant to AI-assisted contributions: the repo is public, .env is committed and must hold placeholders only, npm run gen pulls upstream main without pinning, and CLAUDE.md itself is authoritative input to AI sessions and should be reviewed accordingly. * Documented gen:last-updated and generated src/lib/ files --------- Co-authored-by: TechHutTV <brandon@techhut.tv>
92 lines
5.1 KiB
Markdown
92 lines
5.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Documentation website for [NetBird](https://netbird.io), an open-source WireGuard-based Zero Trust Networking platform. Built with Next.js 16 (Pages Router), React 19, MDX, and Tailwind CSS 3. Requires Node.js >=20.9 — `npm run build` exits with code 1 on older versions.
|
|
|
|
There is no test suite in this project. Validate changes with `npm run build`.
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
npm install # Install dependencies
|
|
npm run dev # Start dev server (also runs gen:llm, gen:edit-routes, gen:last-updated)
|
|
npm run build # Production build (also runs gen:llm, gen:edit-routes, gen:last-updated)
|
|
npm run start # Serve the production build
|
|
npm run lint # ESLint (next/core-web-vitals) on src/
|
|
npm run gen # Regenerate API docs from NetBird OpenAPI spec
|
|
npm run gen:llm # Regenerate LLM-friendly markdown (auto-runs with dev/build)
|
|
npm run gen:edit-routes # Regenerate edit-on-GitHub routes (auto-runs with dev/build)
|
|
npm run gen:last-updated # Regenerate per-page git last-modified dates (auto-runs with dev/build)
|
|
```
|
|
|
|
## Security boundaries
|
|
|
|
- **Public site, public repo.** Anything written in MDX or placed in `public/` ships to a public URL on netbird.io. Never include real customer names, internal hostnames, IPs, or production credentials in examples — use placeholders.
|
|
- **`.env` is committed and contains placeholders only** (e.g. `NEXT_PUBLIC_DOCSEARCH_API_KEY=APP_NEXT_PUBLIC_DOCSEARCH_API_KEY`). These are build-time substitution targets. Real values belong in `.env.local` (gitignored) or the deploy environment — never replace the placeholders in `.env` with real secrets.
|
|
- **`npm run gen` pulls `openapi.yml` live from `netbirdio/netbird@main` with no pinning.** Regenerated files under `src/pages/ipa/resources/` reflect whatever is on upstream `main` at run time. Review the diff before committing.
|
|
- **This file is read as authoritative guidance by AI agents.** Treat edits to `CLAUDE.md` with the same review rigor as CI config or a deploy script.
|
|
|
|
## Architecture
|
|
|
|
### Content Structure
|
|
Documentation pages are MDX files in `src/pages/` using the Next.js Pages Router (not App Router). Key directories:
|
|
- `about-netbird/` - Conceptual docs
|
|
- `get-started/` - Installation and quickstart guides
|
|
- `manage/` - Feature documentation (peers, networks, DNS, access control, etc.)
|
|
- `selfhosted/` - Self-hosting deployment guides
|
|
- `ipa/` - API documentation (served at `/api` via rewrite)
|
|
- `use-cases/` - Tutorials and examples
|
|
- `client/` - Client configuration
|
|
- `help/` - Troubleshooting
|
|
|
|
### MDX Page Conventions
|
|
- Page title comes from the first `# Heading` in the MDX file
|
|
- Optional `export const description = '...'` for meta description
|
|
- Import components as needed: `import {Note} from "@/components/mdx"`
|
|
- Images go in `public/docs-static/img/<section>/` and are referenced as `/docs-static/img/<section>/filename.png`
|
|
|
|
### Navigation
|
|
Two sidebar files, both must be kept in sync when adding or moving pages:
|
|
- `src/components/NavigationDocs.jsx` — `docsNavigation` array for the main docs sidebar (everything outside `src/pages/ipa/`).
|
|
- `src/components/NavigationAPI.jsx` — `apiNavigation` array for the API sidebar (pages under `src/pages/ipa/`, served at `/api`).
|
|
|
|
Both support nested `links` arrays for sub-navigation.
|
|
|
|
### MDX Components
|
|
Custom components available in MDX files (see `README.md` for full usage examples):
|
|
- Alert boxes: `<Note>`, `<Warning>`, `<Success>` (from `@/components/mdx`)
|
|
- Layout: `<Row>`, `<Col>`, `<Tiles>` (from `@/components/Tiles`), `<CodeGroup>`
|
|
- Media: `<YouTube videoId="...">` (from `@/components/YouTube`)
|
|
- UI: `<Button>` (from `@/components/Button`), `<Badge>`
|
|
- API docs: `<Properties>`, `<Property>`
|
|
|
|
### API Documentation Generator
|
|
- `generator/` - TypeScript generator that creates MDX pages from the NetBird OpenAPI spec
|
|
- `generator/templates/ApiTemplate.ts` - Template for generated pages
|
|
- Output: `src/pages/ipa/resources/` (don't edit these files manually)
|
|
|
|
### MDX Processing Pipeline
|
|
- `mdx/remark.mjs` - Remark plugins
|
|
- `mdx/rehype.mjs` - Rehype plugins (syntax highlighting via Shiki)
|
|
- `mdx/recma.mjs` - Recma plugins
|
|
|
|
### LLM Documentation
|
|
- `scripts/generate-llm-docs.mjs` generates clean markdown to `public/llms/` (gitignored)
|
|
- Runs automatically with `dev` and `build`
|
|
|
|
### Generated build data in `src/lib/`
|
|
Some files in `src/lib/` look hand-written but are generated by `gen:*` scripts and gitignored:
|
|
- `src/lib/edit-on-github-routes.js` — written by `scripts/generate-github-routes.mjs`
|
|
- `src/lib/last-updated-routes.mjs` — written by `scripts/generate-last-updated.mjs`
|
|
|
|
They are imported at build time (e.g. by `mdx/rehype.mjs`). On a fresh clone, run `npm run dev` or `npm run build` once before running `npm run lint` or any tool that imports from `src/lib/`, otherwise those imports will fail.
|
|
|
|
## URL Routing
|
|
|
|
- Root `/` rewrites to `/introduction`
|
|
- `/api/*` rewrites to `/ipa/*` (API docs live in `src/pages/ipa/` but are served under `/api`)
|
|
- Extensive legacy redirects from `/docs/*` and `/how-to/*` paths in `next.config.mjs`
|