Docusaurus
Most product documentation does not need one site. It needs three: a reference manual that must keep working for readers who are still on an old release, a blog that changes every week, and a marketing page that a designer wants to rearrange without triggering a rebuild of the docs pipeline. Teams that serve these from three separate tools end up with three build systems, three navigation models, three search indexes, and three places where a broken link goes unnoticed. Docusaurus exists to collapse that into a single project, where a documentation page, a blog post, and a landing page are all routes produced by the same build and served from the same deployment.
The central decision is easy to state: Docusaurus is a React-based static site generator that treats every piece of content as an MDX file inside a folder, and derives the navigation from the folder structure. Almost every other behavior of the tool follows from that. Because the document format is MDX, a page can hold ordinary Markdown and arbitrary React components in the same file, so an interactive demo can sit two paragraphs below a code sample without a plugin or a custom build step. Because the output is static, publishing a documentation fix means rebuilding and copying files rather than provisioning a server and a database. Because the site is one project, the sidebar, the blog archive, the search index, the sitemap, and the translated routes are all derived from the same configuration instead of being wired together by hand.
The mental model worth building before touching the tool is a three-layer one. Content plugins read a source directory and emit routes; the theme layer renders those routes into a consistent interface; and the surrounding React application ties everything together with client-side routing, search, and the small number of interactive widgets a docs site needs. A configuration file wires the three layers together, which is why that file is the place you will spend most of your time. Once you can read a Docusaurus configuration and say which plugin owns which folder, the rest of the tool stops feeling like a black box.
Docusaurus also inherits the wider React ecosystem, and for many teams that is the deciding factor. Components written for an existing product application can be dropped into a documentation page directly. Internationalization is a first-class feature rather than a bolt-on, search can be delegated to Algolia or served locally, admonitions, tabs, live code blocks, and diagram support are built in, and a build fails loudly when a link points nowhere. For a documentation site that lives next to a large React codebase, that combination is unusually hard to reproduce with a lighter generator.
By the end of this chapter you should be able to scaffold a site, author pages that mix prose and components, organize reference material with a sidebar and a category tree, publish a blog alongside the reference, snapshot the documentation into a versioned archive, and extend the build with a plugin or restyle it with a theme. The pages that follow walk through those capabilities in the order you will actually meet them: what the tool is and how it is put together, how to get a project running, how docs and blogs are modeled, how MDX lets you write documents as React, and how plugins and themes let you bend the defaults without forking the project.
