This document provides an overview of the deployment strategies for Docusaurus sites and the release process for the Docusaurus framework itself. It details the build pipeline, local testing, hosting options, and the semantic versioning workflow used by the core team.
For details on hosting providers and configuration, see Deployment Options. For details on the framework's publishing workflow, see Release Process.
Docusaurus is a static site generator. The deployment process begins with generating a static version of the site that can be served by any web server.
The docusaurus build command orchestrates the transformation of source files into a production-ready build/ directory.
Sources: packages/docusaurus/src/commands/build/build.ts36-110 packages/docusaurus/src/webpack/base.ts56-79 packages/docusaurus/src/webpack/client.ts131-143 packages/docusaurus/src/webpack/server.ts16-22
Before deploying, the docusaurus serve command allows developers to test the production build locally. It uses serve-handler to simulate a production environment, handling baseUrl and trailingSlash configurations.
docusaurus serve packages/docusaurus/src/commands/serve.ts36-39serve() in packages/docusaurus/src/commands/serve.ts--build is passed packages/docusaurus/src/commands/serve.ts45-50 It handles redirects to the correct baseUrl and applies trailingSlash normalization to match production behavior packages/docusaurus/src/commands/serve.ts67-90Docusaurus supports a wide range of deployment targets. The framework is designed to be host-agnostic, emitting only standard static files.
| Strategy | Implementation | Key Configuration |
|---|---|---|
| Jamstack | Netlify, Vercel, Cloudflare Pages | url, baseUrl |
| GitHub Pages | docusaurus deploy command | organizationName, projectName, deploymentBranch |
| Self-Hosting | Nginx, Apache, or docusaurus serve | trailingSlash, port, host |
Sources: README.md25-27 packages/docusaurus/src/commands/deploy.ts134-154
The deploy command specifically automates the process of building and pushing to a remote branch (usually gh-pages).
Sources: packages/docusaurus/src/commands/deploy.ts76-115 packages/docusaurus/src/commands/deploy.ts285-320
For a deep dive into platform-specific setups, see Deployment Options.
The Docusaurus framework uses a monorepo structure managed by Lerna and Yarn Workspaces. Releases are coordinated across all @docusaurus/* packages to ensure version parity.
latest tag using Trusted Publishing (OIDC). admin/publish.md20-25pkg-pr-new or OIDC for every commit to the main branch. CHANGELOG.md53-54docusaurus-vX branches (e.g., docusaurus-v3-maintenance) when main has moved to a new major version. admin/publish.md71-85The core team follows a strict manual checklist for stable releases:
admin/scripts/test-release.sh script. admin/scripts/test-release.sh40-48pnpm changelog --from <tag> based on GitHub PR labels. admin/publish.md32-34pnpm lerna version <version> --exact to ensure all internal dependencies are pinned. admin/publish.md51Publish workflow on GitHub Actions, which utilizes npm Trusted Publishing. admin/publish.md53-59For details on the specific commands and administrative steps, see Release Process.
To ensure clean builds and avoid cache-related issues, Docusaurus provides a utility to purge temporary files.
docusaurus clear packages/docusaurus/src/commands/clear.ts33.docusaurus/), the build output folder (build/), and bundler persistent cache folders in node_modules or .yarn. packages/docusaurus/src/commands/clear.ts36-51Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.