Documentation

Documentation

The Root README Is The Only README

README.md at the repository root is the single hand-maintained README. The root package:prepare script builds every package and then runs deploy/copy-readme.cjs once, which copies it into all eight packages/* directories; every package:latest, package:next, package:rc, and package:tgz run starts with that step, so published tarballs always ship it, including in CI. .gitignore excludes packages/*/README.md so no package carries a tracked copy. Never hand-write a package README expecting it to survive: edit the root README instead, and let the packaging step distribute it.

Because one file serves every package, keep it oriented to the reader arriving at any one of them: what nestia is, the feature list per package, installation, the smallest working setup, and links onward to the guides. Move deep explanations into the website guides rather than growing the README to cover them.

Guide Documents

User-facing guides live under website/src/content/docs/** as MDX and publish at https://nestia.io/docs. The site runs Nextra 4 on Next.js with output: "export", and deploys the static website/out tree to the gh-pages branch. Keep one audience and one task per page.

The tree is organized by the surface a reader is working with:

• top-level index.mdx and setup.mdx cover introduction and installation;
• core/ owns one page per decorator (TypedRoute, TypedBody, TypedParam, TypedQuery, TypedFormData, TypedHeaders, TypedException, PlainBody, SwaggerExample, SwaggerCustomizer, WebSocketRoute, McpRoute);
• sdk/ covers SDK generation, distribution, monorepo layout, generated e2e, and the mockup simulator;
• swagger/ covers the Swagger document, its editor and chat surfaces, and generation strategy;
• e2e/ covers why generated e2e exists, how to develop against it, and benchmarking.

The site carries no beginner walkthrough at present. A ten-step tutorial once sat at website/src/content/tutorial/** and published at https://nestia.io/tutorial, but it shipped unfinished and was withdrawn; the restoration is pending in its own pull request. Do not reintroduce /tutorial links into docs/** until that work lands.

Every docs folder and src/content/ itself carries a _meta.ts that Nextra reads in declaration order for sidebar order and labels. Two of them — src/content/_meta.ts and src/content/docs/_meta.ts — use the typed satisfies MetaRecord form; the four per-feature folders use the plain default-exported object. Beyond ordering, those meta files carry type: "page" | "menu" | "separator" for navigation structure, display: "hidden" to keep a page reachable while removing it from the sidebar, and href to point an entry at a different target — mostly internal routes such as /api, /blog, and /editor, and occasionally an external URL. Update the matching _meta.ts whenever a guide is added, renamed, moved, hidden, or exposed.

When emitted code is the point, pair the TypeScript source with the generated SDK, Swagger, or e2e output in side-by-side tabs so the reader sees what the transform produces. Back performance claims with a specific benchmark/results/** figure instead of an adjective.

Building the website is not a plain next build. Follow the prerequisites in .agents/skills/development/SKILL.md: the site depends on ../deploy/tarballs/editor.tgz and ../deploy/tarballs/migrate.tgz, so root pnpm run package:tgz must run first, and prebuild additionally rebuilds @nestia/migrate and @nestia/editor and runs TypeDoc over five packages into website/public/api.