CLI

Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.

Once your website is bootstrapped, the website source will contain the Docusaurus scripts that you can invoke with your package manager:

package.json

{
  // ...
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids"
  }
}

Docusaurus CLI commands

Below is a list of Docusaurus CLI commands and their usages:

`docusaurus start [siteDir]`

Builds and serves a preview of your site locally with Webpack Dev Server.

Options

Name	Default	Description
`--port`	`3000`	Specifies the port of the dev server.
`--host`	`localhost`	Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`.
`--locale`		Specify site locale to be used.
`--hot-only`	`false`	Enables Hot Module Replacement without page refresh as a fallback in case of build failures. More information here.
`--no-open`	`false`	Do not open the page automatically in the browser.
`--config`	`undefined`	Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js`
`--poll [optionalIntervalMs]`	`false`	Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information here.
`--no-minify`	`false`	Build website without minimizing JS/CSS bundles.
`--https`	`false`	Serve the dev site over HTTPS using a self-signed certificate. Implied when both `--ssl-cert` and `--ssl-key` are provided.
`--ssl-cert`	`undefined`	Path to a TLS certificate file (implies HTTPS).
`--ssl-key`	`undefined`	Path to a TLS private key file (implies HTTPS).

Development over network

When forwarding port 3000 from a remote server or VM (e.g. GitHub Codespaces), you can run the dev server on 0.0.0.0 to make it listen on the local IP.

npm2yarn

npm run start -- --host 0.0.0.0

Enabling HTTPS

There are multiple ways to obtain a certificate. We will use mkcert as an example.

Run mkcert localhost to generate localhost.pem + localhost-key.pem
Run mkcert -install to install the cert in your trust store, and restart your browser
Start the app with the Docusaurus HTTPS CLI options:

npm2yarn

npm run start -- --ssl-cert localhost.pem --ssl-key localhost-key.pem

Open https://localhost:3000/

`docusaurus build [siteDir]`

Compiles your site for production.

Options

Name	Default	Description
`--dev`		Builds the website in dev mode, including full React error messages.
`--bundle-analyzer`	`false`	Analyze your bundle with the webpack bundle analyzer.
`--out-dir`	`build`	The full path for the new output directory, relative to the current workspace.
`--config`	`undefined`	Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js`
`--locale`		Build the site in the specified locale(s). If not specified, all known locales are built.
`--no-minify`	`false`	Build website without minimizing JS/CSS bundles.

`docusaurus swizzle [themeName] [componentName] [siteDir]`

Swizzle a theme component to customize it.

npm2yarn

npm run swizzle [themeName] [componentName] [siteDir]

# Example (leaving out the siteDir to indicate this directory)
npm run swizzle @docusaurus/theme-classic Footer -- --eject

The swizzle CLI is interactive and will guide you through the whole swizzle process.

Options

Name	Description
`themeName`	The name of the theme to swizzle from.
`componentName`	The name of the theme component to swizzle.
`--list`	Display components available for swizzling
`--eject`	Eject the theme component
`--wrap`	Wrap the theme component
`--danger`	Allow immediate swizzling of unsafe components
`--typescript`	Swizzle the TypeScript variant component
`--javascript`	Swizzle the JavaScript variant component
`--config`	Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js`

`docusaurus deploy [siteDir]`

Deploys your site with GitHub Pages. Check out the docs on deployment for more details.

Options

Name	Default	Description
`--locale`		Deploy the site in the specified locale(s). If not specified, all known locales are deployed.
`--out-dir`	`build`	The full path for the new output directory, relative to the current workspace.
`--skip-build`	`false`	Deploy website without building it. This may be useful when using a custom deploy script.
`--target-dir`	`.`	Path to the target directory to deploy to.
`--config`	`undefined`	Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js`

`docusaurus serve [siteDir]`

Serve your built website locally.

Name	Default	Description
`--port`	`3000`	Use specified port
`--dir`	`build`	The full path for the output directory, relative to the current workspace
`--build`	`false`	Build website before serving
`--config`	`undefined`	Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js`
`--host`	`localhost`	Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`.
`--no-open`	`false` locally, `true` in CI	Do not open a browser window to the server location.

`docusaurus clear [siteDir]`

Clear a Docusaurus site's generated assets, caches, build artifacts.

We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site.

`docusaurus write-translations [siteDir]`

Write the JSON translation files that you will have to translate.

By default, the files are written in website/i18n/<defaultLocale>/....

Name	Default	Description
`--locale`	`<defaultLocale>`	Define which locale folder you want to write translations the JSON files in
`--override`	`false`	Override existing translation messages
`--config`	`undefined`	Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js`
`--messagePrefix`	`''`	Allows adding a prefix to each translation message, to help you highlight untranslated strings

`docusaurus write-heading-ids [siteDir] [files]`

Add explicit heading IDs to the Markdown documents of your site.

Name	Default	Description
`files`	All MD files used by plugins	The files that you want heading IDs to be written to.
`--syntax`	`classic`	Heading ID syntax to use: `classic` (`{#id}`) or `mdx-comment` (`{/* #id */}`).
`--migrate`	`false`	Migrate existing heading IDs to the target `--syntax`, if they are using a different syntax.
`--overwrite`	`false`	Overwrite existing heading IDs, re-generate them from the heading text.
`--maintain-case`	`false`	Keep the headings' casing, otherwise make all lowercase.