Docusaurus: install it, run it, and know when it is the wrong choice

The maintenance problem Docusaurus is built to remove

Most open source projects do not fail at writing documentation. They fail at keeping it alive. A docs site is a second codebase with its own dependencies, its own deploy pipeline and its own upgrade cycle, and it competes for time with the actual project. Docusaurus targets that specific cost. The README states the project is for "building, deploying, and maintaining open source project websites easily," and the framing is deliberate: the generator ships with a home page, a docs section, a blog and support pages already assembled, so the first version of the site exists before you write layout code.

The intended audience is a project that already has Markdown files and a repository, and wants versioned documentation, a blog and translated pages without building any of that from scratch. The repository layout reflects this. The examples directory holds classic and classic-typescript starters, the website directory holds the project's own documentation site, and the packages directory holds the published modules. Docusaurus is not a general purpose static site generator for marketing pages. It is a documentation tool with opinions about information architecture, and the opinions are the product.

What happens between a Markdown file and a served page

Docusaurus is a build-time generator with a React runtime on the client. You write Markdown and MDX under a docs directory, and the build step turns each file into a route. The repository is a pnpm workspace: package.json defines build:packages as a Lerna run across the non-private packages, and build:website as a filtered build of the website package. The root build script chains the two, so the published packages are compiled before the documentation site that consumes them.

The consequence for adopters is that a Docusaurus site is a Node build, not a file copy. The output is static HTML plus JavaScript bundles, which is why the project can be deployed to static hosts, but it also means the build has a dependency tree and a bundler inside it. The repository's own scripts hint at how much tuning is possible: start:website:profile and build:website:profile set DOCUSAURUS_BUNDLER_CPU_PROFILE and DOCUSAURUS_RSPACK_TRACE, which suggests the bundler exposes profiling hooks when a build gets slow. That is a real capability, and it is also a signal that build performance is something maintainers of large sites end up looking at.

On the content side, localization is handled through Crowdin. The repository carries a crowdin-v2.yaml file, and the README describes localization support via Crowdin rather than an in-repo translation workflow. Theming works through swizzling, which the documentation covers as a distinct concept: you take a theme component and replace or wrap it. That is the extension point, and it is why the build script includes a swizzle wrap test before a deploy preview build.

Installing Docusaurus and getting a first page served

The README gives one installation path: the initialization CLI. It is published as a package, so the command runs through npm and creates a site scaffold rather than adding a dependency to an existing project.

npm init docusaurus@latest

The CLI asks for a site name and a template. The repository ships two examples that correspond to the common choices, examples/classic and examples/classic-typescript, and the README links a five-minute tutorial at tutorial.docusaurus.io for the guided version. If you would rather not create anything locally, the README points to docusaurus.new as a playground, and it also links a Vercel clone URL that targets examples/classic, which deploys the starter directly.

Once the scaffold exists, the development server is the normal npm script inside the generated site. The root package.json in this repository shows the equivalent for the project's own site, where start:website filters to the website package and runs its start script. In a generated site you run the same script from the site directory.

npm run start

You should see a local development server with the starter home page, a docs route, and a blog route. Editing a Markdown file under docs triggers a rebuild in the browser. The first real use worth trying after that is adding one page: create a Markdown file in the docs directory, give it front matter, and confirm the sidebar picks it up. If the sidebar entry does not appear, the front matter or the sidebar configuration is the place to look, not the build.

Swizzling is the power and the upgrade cost

Swizzling is how you change what Docusaurus renders without forking it. You copy a theme component into your site, or wrap it, and the build uses your version. This is the mechanism behind most custom layouts, and it is also the mechanism that creates upgrade work. A swizzled component is a snapshot of the theme at the version you copied it, so a later Docusaurus release can change the same component and your copy will not follow. The repository's deploy preview script runs a swizzle wrap test before building, which tells you the maintainers treat wrapper compatibility as something to check on every change. Your site does not get that check for free.

The practical rule the documentation implies is to swizzle as little as possible and prefer wrapping over replacing. Wrapping keeps the upstream component in the tree and layers your change on top, so upstream fixes still reach the page. Replacing removes it, and you own the whole component from then on. Neither approach is wrong, but the cost is asymmetric and it compounds across releases. A site with three wrapped components is a weekend upgrade. A site with thirty replaced components is a project.

Where Docusaurus is the wrong tool

The clearest mismatch is a documentation set that has no React component in it and never will. Docusaurus brings a bundler, a client runtime and a plugin system to a job that a Markdown to HTML converter can do. If your pages are prose, code blocks and images, and your team has no JavaScript build in CI, the toolchain is pure overhead. The build has to run somewhere, the Node version has to be pinned somewhere, and every dependency advisory in that tree becomes your problem even though you never wrote a component.

A second mismatch is content that changes faster than a build pipeline can tolerate. Docusaurus generates a static site, so publishing means rebuilding and redeploying. The documentation describes the build and deploy workflow, but it does not describe a live editing mode where a non-technical writer changes a page and sees it published without a commit. Teams that need that workflow are looking at a hosted documentation product, not a generator.

A third case is a site that is mostly a marketing page with a small help section attached. Docusaurus ships a home page and support pages, but its structure assumes the docs are the center. If the docs are an appendix, the information architecture will fight you.

Docusaurus against MkDocs, and what the difference actually is

The comparison people search for is Docusaurus versus MkDocs, and the difference is the runtime, not the file format. Both take Markdown and produce a static site. MkDocs is a Python tool that renders Markdown through a theme, and its output is largely HTML with a small amount of JavaScript for navigation and search. Docusaurus is a TypeScript and React project. Its pages can contain React components, its theme is swizzlable at the component level, and its build runs through a JavaScript bundler.

That difference decides the choice more than any feature list. If your documentation needs interactive examples, embedded components that share code with your application, or a theme customized at the component level, MkDocs will require workarounds where Docusaurus has a supported path. If your documentation is Markdown and a theme, MkDocs gives you the same reader experience with a much smaller dependency surface and a Python toolchain your team may already have. The versioning story differs too: Docusaurus treats versioned docs as a first-class concept, while MkDocs reaches similar results through plugins. Neither is a superset of the other, and the deciding question is whether React is part of your documentation or an extra build step.

Licence, releases and what an upgrade actually costs

Docusaurus is MIT licensed, and the README separates that from the documentation content: the `.md` files in the docs folder are covered by a Creative Commons licence, with LICENSE-docs in the repository. For most adopters this means the generator code carries no copyleft obligation and the licence file ships with the package. The split matters if you copy documentation text rather than use the tool, because the two licences are not the same. That is a description of what the repository states, not legal advice.

The release cadence visible in the repository is steady: 3.10.0 on 2026-04-07, 3.10.1 on 2026-04-30, and 3.10.2 on 2026-07-10, with the last push to the main branch on 2026-07-10. Major versions are where the cost lives. A site that uses the default theme and no swizzled components upgrades by changing a version number and reading the changelog. A site with swizzled components upgrades by diffing each one against the new theme. The repository keeps CHANGELOG.md and CHANGELOG-v2.md at the root, so the release notes are the place to check before bumping. Budget the upgrade as a function of how many components you replaced, not how many pages you wrote.

Editorial conclusion

Adopt Docusaurus if you want a React-based docs site with versioned documentation, blog and i18n support under an MIT licence, and you are comfortable with the Node and pnpm toolchain. Do not adopt it if your documentation is plain Markdown with no React involvement and you want the smallest possible build: MkDocs handles that case with less machinery. Before committing, verify three things in your own environment: the Node version your CI image provides, whether your hosting target supports a static build with client-side search, and how much of the theme you would need to swizzle for your layout.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes