This document covers the initial installation and setup of Docusaurus for new users. It explains the initialization process via create-docusaurus, the resulting project scaffold, directory structures, and the core CLI commands.
Docusaurus requires Node.js version 24.14 or higher. This requirement is enforced across the monorepo and in the initialization templates.
| Requirement | Version | Source |
|---|---|---|
| Node.js | >=24.14 | packages/create-docusaurus/package.json37-39 website/docs/installation.mdx24 |
| Package Manager | npm, yarn, pnpm, or bun | packages/create-docusaurus/src/constants.ts20-21 packages/create-docusaurus/bin/index.js33-36 |
| TypeScript (Optional) | ~6.0.2 | examples/classic-typescript/package.json33 website/docs/typescript-support.mdx9 |
Sources: packages/create-docusaurus/package.json37-39 website/docs/installation.mdx24 packages/create-docusaurus/src/constants.ts20-21 packages/create-docusaurus/bin/index.js33-36 examples/classic-typescript/package.json33 website/docs/typescript-support.mdx9
The recommended way to start a new project is using the create-docusaurus CLI tool. This package is designed to be lightweight and handles the scaffolding of new sites from predefined templates.
When a user runs npm init docusaurus or npx create-docusaurus@latest, the create-docusaurus binary executes the following logic:
package.json packages/create-docusaurus/bin/index.js23-27prompts library packages/create-docusaurus/src/index.ts17-18:
classic), a Git repository, or a local path packages/create-docusaurus/src/index.ts215-240findPackageManagerFromLockFile or prompts the user packages/create-docusaurus/src/index.ts62-72 packages/create-docusaurus/src/index.ts110-132shared template directory to the destination packages/create-docusaurus/src/index.ts181-183classic or classic-typescript) while filtering out symbolic links packages/create-docusaurus/src/index.ts185-194--skip-install is passed, it triggers runPackageManagerInstallCommand to fetch dependencies packages/create-docusaurus/src/index.ts31 packages/create-docusaurus/src/index.ts110-132The following diagram illustrates how the create-docusaurus package transforms user input and template files into a functional project.
Sources: packages/create-docusaurus/src/index.ts181-194 packages/create-docusaurus/src/index.ts138-174 packages/create-docusaurus/src/index.ts52-60 packages/create-docusaurus/src/index.ts110-132 packages/create-docusaurus/src/index.ts246-249 packages/create-docusaurus/src/index.ts215-240 packages/create-docusaurus/bin/index.js23-27 packages/create-docusaurus/src/commands.ts31
Docusaurus provides several templates, with classic being the recommended starting point. It includes @docusaurus/preset-classic which provides standard documentation, a blog, and custom pages website/docs/installation.mdx35
A project initialized with the classic template (JavaScript) contains:
The scaffolding logic merges a shared directory with a specific template variant to reduce duplication.
sidebars.js and basic directory structures packages/create-docusaurus/src/index.ts181-183package.json dependencies and docusaurus.config.js tailored for the chosen language (JS vs TS) packages/create-docusaurus/src/index.ts185-192 TypeScript variants include a tsconfig.json extending @docusaurus/tsconfig packages/create-docusaurus/templates/classic-typescript/tsconfig.json1-3Sources: packages/create-docusaurus/src/index.ts181-183 packages/create-docusaurus/src/index.ts185-192 examples/classic/package.json1-47 website/docs/installation.mdx98-105
The generated package.json includes the minimal set of packages required to run a Docusaurus site.
| Package | Role | Source |
|---|---|---|
@docusaurus/core | The core engine and build pipeline. | examples/classic/package.json18 |
@docusaurus/faster | Opt-in performance optimizations for build/start. | examples/classic/package.json19 |
@docusaurus/preset-classic | Bundle containing Docs, Blog, and Pages plugins. | examples/classic/package.json20 |
react & react-dom | UI library (v19+ supported). | examples/classic/package.json24-25 |
@mdx-js/react | MDX support for React components. | examples/classic/package.json21 |
typescript | Required for TS variants. | examples/classic-typescript/package.json33 |
Sources: examples/classic/package.json18-25 examples/classic-typescript/package.json33
The Docusaurus CLI provides the interface for development and production workflows. The entry point for Docusaurus sites is the docusaurus binary, which executes beforeCli.mjs for version and environment checks before running commands packages/docusaurus/bin/beforeCli.mjs48-175
In the generated package.json, the following scripts are mapped to CLI commands:
npm start: Runs docusaurus start. Serves a local preview with HMR at localhost:3000 examples/classic/package.json7 website/docs/cli.mdx32-40npm run build: Runs docusaurus build. Compiles the site into static assets in the build/ directory examples/classic/package.json8 website/docs/cli.mdx94-108npm run swizzle: Runs docusaurus swizzle. An interactive CLI to wrap or eject theme components examples/classic/package.json9 website/docs/cli.mdx117-143npm run deploy: Runs docusaurus deploy. Automates deployment to GitHub Pages examples/classic/package.json10 website/docs/cli.mdx150-160npm run clear: Runs docusaurus clear. Deletes generated files and caches like .docusaurus and build examples/classic/package.json11npm run serve: Runs docusaurus serve. Serves the production build locally for testing examples/classic/package.json12Sources: packages/docusaurus/bin/beforeCli.mjs48-175 examples/classic/package.json5-16 website/docs/cli.mdx32-160
The docusaurus.config.js (or .ts) file is the primary configuration file. It uses JSDoc or TypeScript types to provide autocompletion for site metadata, presets, and theme configuration examples/classic/docusaurus.config.js1-12
title, url, baseUrl, and favicon examples/classic/docusaurus.config.js13-26classic preset, including paths for docs, blog, and custom CSS examples/classic/docusaurus.config.js43-75navbar items, footer links, and prism syntax highlighting themes examples/classic/docusaurus.config.js77-155Sources: examples/classic/docusaurus.config.js12-156 website/docs/typescript-support.mdx68-144
For rapid testing without local installation, Docusaurus provides:
classic and classic-typescript templates used by the CLI examples/README.mdSources: admin/new.docusaurus.io/README.md examples/README.md
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.