mirror of https://github.com/netbirdio/docs.git synced 2026-05-06 01:06:36 +00:00

Files

Jack Carter e22a81509e docs: refresh CLAUDE.md for Next 16 toolchain and API sidebar (#725 )

* 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>

2026-05-04 10:19:41 -07:00

5.1 KiB

Raw Blame History

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, 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

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

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

5.1 KiB Raw Blame History