Docusaurus

Last reviewed Aug 26, 2026 · 813 words

Self-hosting Docusaurus is a category error in the best way: there is no Docusaurus server. The build step spits out plain HTML, CSS, and JavaScript, and any web server — nginx, Caddy, even a $4/month VPS with 256 MB free — serves it. The 512 MB RAM figure in the catalogue is for the build, not the hosting, and the build usually runs on your laptop or in CI anyway. What you are actually choosing when you pick Docusaurus is a writing workflow: Markdown files in Git, no web editor, and the best versioned-docs story in open source.

The output is static, so hosting is the easy part

npm run build produces a build/ directory of flat files. Copy it to a web root and you are live. A typical docs site weighs a few MB; a container running nginx to serve it idles at under 10 MB of RAM. Compare that with a wiki like BookStack, which needs PHP and a database running 24/7 to show the same paragraph of text. The static model also means your docs stay up when everything else is on fire — there is nothing to crash, and a broken deploy just means the old version keeps serving.

The flip side: every content change requires a rebuild. On a small site that is 20–60 seconds; sites with thousands of pages can take several minutes, and MDX compilation is the usual bottleneck. Wire it into CI so a push to main rebuilds and syncs the output, and the friction mostly disappears.

Versioning is the feature you actually chose it for

Docusaurus, built by Meta and open-sourced in 2017 (MIT, TypeScript, 66,083 GitHub stars), earns its keep the day you ship v2 of your software while users still run v1. One command snapshots the current docs as a frozen version; the sidebar grows a version dropdown; you keep editing next while 1.x stays readable. Internationalization works the same way — parallel translated trees the build stitches together. Almost nothing else in the wikis category does either of these well, and hand-rolling versioned docs in a wiki is a maintenance tax you pay forever.

If you do not need versions or translations, you are paying Docusaurus's React complexity for nothing, and MkDocs with the Material theme gets you a comparable site from a Python toolchain with less machinery.

Search is a decision, not a default

Out of the box there is no search. Your two realistic options: Algolia DocSearch, which is free for open-source docs but means a third-party service crawling your site — an odd fit if you went self-hosted for data control — or a local search plugin (the community docusaurus-search-local family) that builds an index at compile time and runs entirely in the browser. Local search is adequate up to a few hundred pages; beyond that the index download starts to hurt first paint. Decide early, because retrofitting search config touches your theme setup.

No web editor is the real cost

The catalogue lists "no web-based editing" as a con, and it is the one that kills Docusaurus for some teams. Every contributor needs Git, a text editor, and enough Node to preview locally (Node 18 or newer for current releases). For a developer-run project that is zero extra cost. For a docs site where support staff or product managers write half the content, it is a wall, and a wiki with a browser editor will get more words written per week regardless of how much nicer your Docusaurus site looks. Be honest about who your writers are before you commit.

Keep Node off the production box

The Medium difficulty rating is entirely about the toolchain: npm dependency trees, MDX version bumps, the occasional breaking change between major releases. Contain all of that in CI. My pattern: a GitHub Actions or Gitea runner job that does npm ci && npm run build, then rsyncs build/ to the server. The production machine never runs Node, never sees node_modules, and updates to Docusaurus itself become a pull request you can revert instead of an SSH session you regret.

What I'd do

For project documentation with releases — an API, a CLI, anything with versions — Docusaurus is my default and the setup is: repo with docs in Markdown, CI job building on push, output rsynced to a static server behind Caddy, local search plugin unless the site is huge. Budget an evening for the initial config and near-zero maintenance after. For an internal knowledge base where non-developers write, skip it and run BookStack instead; the editor in the browser matters more than the prettier output. And if the whole React layer feels like too much for a README that outgrew itself, MkDocs is the lighter path to the same place.