How to Deploy a Docusaurus Documentation Site

Docusaurus, Meta's React-based static-site generator, is one of the most popular tools for technical documentation. It produces a fully static build that's cheap and fast to host. The deployment is straightforward once you get a couple of configuration details right, primarily the build command and the url/baseUrl settings, and then it's a matter of continuous deploys from Git. This guide walks through it.

How Docusaurus builds

A Docusaurus site is a React app that's pre-rendered to static HTML at build time. The command:

npm run build

runs docusaurus build, which outputs a fully static site to the build/ directory, HTML, JS, CSS, and assets. There's no server runtime; you serve those files from a static host or CDN. This is the key fact that makes Docusaurus cheap to host and trivial to scale: it's just files.

The url and baseUrl settings

The single most common Docusaurus deployment mistake is misconfiguring url and baseUrl in docusaurus.config.js. These control how internal links and assets are generated:

export default {
  title: 'My Docs',
  url: 'https://docs.example.com', // your production origin, no trailing path
  baseUrl: '/',                    // '/' if served at the root
  // baseUrl: '/docs/',            // if served under a subpath
};

If you serve the site at the root of a domain (the usual case), baseUrl is /. If it lives under a subpath like example.com/docs/, set baseUrl to /docs/, otherwise CSS and links break with 404s. Get these right before your first deploy and you'll avoid the classic "site loads but is unstyled" problem.

Search and versioning

Two Docusaurus features have deployment implications:

• Search: the common options are Algolia DocSearch (hosted, requires an app ID and API key as build-time config) or a local/offline search plugin that builds an index into the static output. Local search keeps everything self-contained; Algolia offloads search infrastructure.
• Versioned docs: Docusaurus can snapshot docs into versioned folders. These are all part of the static build, no special hosting needed, but they increase build size and time. Be aware of build-minute consumption if you maintain many versions.

Deploying on PandaStack

Docusaurus is a static site, so it deploys as a static site app, which means it builds in a fast microVM and serves from a CDN-backed edge rather than running a container.

1. 1Push your Docusaurus project to GitHub.
2. 2In the dashboard, create a static site and connect the repo.
3. 3PandaStack auto-detects the framework. It identifies the build command (npm run build) and the publish directory (build). You can override the install command to use yarn, pnpm, or bun if that's what your project uses.
4. 4The static build runs in a pandastack.ai microVM, fast and isolated, and the output is published to the edge with automatic SSL.
5. 5Watch the live build logs to confirm the build succeeded and pages were generated.

Continuous deploys

Once connected, every push to your default branch triggers a rebuild and redeploy, so your docs stay in sync with your code. This is exactly the workflow docs sites want: a contributor merges a docs PR, the site updates automatically. Deploy history lets you see past deploys and roll back if a build introduces a problem.

Custom domains and SSL

Docs almost always live on a branded subdomain like docs.example.com. Add the custom domain in the dashboard and point a CNAME at the provided target; SSL is issued and renewed automatically. No certificate management on your end.

Performance notes

Because the output is static and served from the edge, performance is excellent out of the box, no cold starts, no server to scale. A few build-time tips:

• Optimize images before committing them; large images bloat the build and slow page loads.
• Keep the number of doc versions reasonable to control build time and size.
• Use the production build locally (npm run serve after npm run build) to catch broken links before deploying; Docusaurus's broken-link checker runs during the build and will fail the deploy on dead internal links, which is a feature, not a bug.

Free tier fit

A static docs site is the ideal free-tier workload. The free tier includes static sites with 100GB bandwidth and 300 build minutes per month, ample for most documentation. Since static sites are served from the edge, there's no scale-to-zero cold-start concern, the files are always there. For larger projects or more frequent builds, the Pro tier raises bandwidth and build minutes and offers unlimited static sites.

Common pitfalls

• Wrong baseUrl, the site loads unstyled or links 404.
• Wrong publish directory, deploy serves nothing or the wrong files (it's build, not dist).
• Broken internal links, the build fails by design; fix the links.
• Unoptimized images, slow pages and wasted bandwidth.

References

• Docusaurus deployment docs: https://docusaurus.io/docs/deployment
• Docusaurus configuration (url/baseUrl): https://docusaurus.io/docs/configuration
• Docusaurus versioning: https://docusaurus.io/docs/versioning
• Algolia DocSearch: https://docsearch.algolia.com/
• Docusaurus broken-link checking: https://docusaurus.io/docs/api/docusaurus-config#onBrokenLinks

Docusaurus produces a static site that's cheap, fast, and simple to host, the main work is getting baseUrl right and connecting continuous deploys. Publish your docs with automatic SSL and Git-based deploys on PandaStack's free tier: https://dashboard.pandastack.io