Installation and Project Structure

A Docusaurus site is a React application that is rendered to static HTML at build time. The installation page of the official documentation lists a single requirement: Node.js 20.0 or above (check it with node -v). Node.js 18 support ended with Docusaurus 3.9. The generated site depends on React 19. npm ships with Node.js; Yarn, pnpm and Bun also work.

The create-docusaurus tool creates a new directory and installs the dependencies. It can be run anywhere, in an empty repository or inside an existing one. The usual form names the site directory and the template:

Source: Docusaurus docs: Installation

The arguments are, in order, the site name, the template and an optional root directory:

The options documented for the tool are listed below. Running npx create-docusaurus@3.10.2 --help prints the same set.

Source: Docusaurus docs: create-docusaurus

The same site can be created with the package manager’s own initializer: npm init docusaurus, yarn create docusaurus, pnpm create docusaurus or bunx create-docusaurus. The official page also mentions a Fast Track tutorial and an online playground at docusaurus.new for trying the tool without installing anything.

Real output of the command above, reduced to its closing summary:

The scaffolded site pins the Docusaurus packages to the exact release that was current when it was created and uses a caret range for React:

Source: Docusaurus docs: Installation

All packages in the @docusaurus/ namespace must use the same version. The official upgrade instructions are to change the versions in package.json, run the package manager’s install command, and check the result with npx docusaurus --version, which prints 3.10.2 here. The @canary npm dist-tag gives access to unreleased features. At the check date the latest tag was 3.10.2, the last release of the 3.x line, and version 4 existed only as canary builds.

The scaffold already contains two things that older tutorials do not mention: the @docusaurus/faster package, and future: { v4: true } in the configuration. The second is a single switch that turns on a group of flags preparing the site for Docusaurus 4, among them the faster toolchain. The effect is visible in the dev server banner, which reports the Rspack bundler (Rspack 1.7.12 in this run). Both are covered in Docusaurus Faster and v4 readiness.

The official page draws the tree of a JavaScript site. The TypeScript variant generated here has the same folders with TypeScript and MDX files, and a few more entries. The listing shows every file, except the images in static/img, the two screenshots in docs/tutorial-extras/img and the banner image of the welcome post:

Source: Docusaurus docs: Installation (Project structure)

Each entry has a role, summarised here and detailed in the pages named in the last column.

Folders that appear later and are not part of the scaffold are i18n/ (translations, created by write-translations or by hand), versioned_docs/, versioned_sidebars/ and versions.json (created by docs:version), and the generated .docusaurus/ and build/ directories.

The plugins of the classic preset turn the folders into routes. The generated site maps as follows:

Figure: folders of the scaffolded project and the routes they produce.

The documentation page on the docs feature gives the same mapping for a fresh site: docs are served under /docs, and blog posts under /blog with the date in the URL unless a slug is set. The three sample posts of the template set a slug in their front matter (for example slug: first-blog-post), so they are served at /blog/first-blog-post, /blog/long-blog-post, /blog/mdx-blog-post and /blog/welcome. Setting the docs option routeBasePath to / serves the documentation at the site root ("docs-only mode"); the blog can be turned off with blog: false in the preset options. Both are shown in Configuration.

Source: Docusaurus docs: Docs introduction

The scaffold defines these scripts in package.json, each calling the docusaurus binary:

Source: Docusaurus docs: CLI

The typecheck script exists only in the TypeScript variant. npx docusaurus --help lists, besides the scripts above, the command docs:version <version>, which tags a new documentation version. Options of each command, as printed by --help in 3.10.2:

Source: Docusaurus docs: CLI

To pass an option through npm, separate it with two dashes, as the official page does for the host option:

Source: Docusaurus docs: CLI

Not every feature works the same in development: the official page notes that some functionality, anchor links among it, only works in the production build. A development-mode production bundle with full React error messages is available with docusaurus build --dev.

From the site directory, npm start opens a browser on port 3000. Running it with --no-open and a different port printed the following:

The production build and its output:

Source: Docusaurus docs: Installation (Build)

The result is a folder of static files that any static hosting service can serve. For the scaffold it contains 404.html, index.html, sitemap.xml, an assets/ folder with hashed JavaScript and CSS, and one folder per route group: docs/, blog/, markdown-page/ and img/. npm run serve -- --no-open -p 3123 served the build, and both the pages and files from static/ answered with status 200.

The Pocket Units documentation fits the scaffold without changing any configuration. The commands and files below add a docs category, one blog post, a standalone page and a static download to a copy of the generated site.

The blog post refers to an author and a tag that must be defined in blog/authors.yml and blog/tags.yml. Because the scaffold sets onInlineAuthors and onInlineTags to warn, an author or tag that is not declared in those files is reported at build time. The two entries appended to the generated files were:

Finally, a file at static/files/units.csv (the single line metre,foot,inch) becomes available at /files/units.csv. The next build succeeded and produced these routes among the routes of the site, as listed in build/sitemap.xml:

Source: Docusaurus docs: Docs introduction

Note how the blog URL (the post sets no slug) takes its date from the folder name, how the docs URLs follow the folder names while the sidebar order follows sidebar_position and the category position, and how the generated-index link type created the extra page /docs/category/pocket-units.