Why Not Just Use a Static Site Generator?

Tools like MkDocs and Docusaurus are fantastic, but we wanted our documentation to be a living part of our main application. We wanted to share components, branding, and a unified design system. Next.js, with its hybrid of static site generation (SSG) and server-side rendering (SSR), was the perfect fit.

Our Architecture

Our approach is simple and powerful:

1. All documentation is written in standard Markdown files stored in a Git repository.
2. On build, Next.js's generateStaticParams function reads our file structure to discover all available doc pages.
3. For each page, we use a library called gray-matter to parse the frontmatter and remark to convert the Markdown content into HTML on the server.
4. This content is then passed as a prop to a React Server Component, which renders the final page.

The result is an incredibly fast user experience. You receive a fully-rendered static HTML page, but we retain the power and flexibility of the entire React ecosystem. This post itself is a product of that very system!