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"
  }
}

Index

• docusaurus start [siteDir]
• docusaurus build [siteDir]
• docusaurus swizzle [siteDir]
• docusaurus deploy [siteDir]
• docusaurus serve [siteDir]
• docusaurus clear [siteDir]
• docusaurus write-translations [siteDir]
• docusaurus write-heading-ids [siteDir] [files]

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.
--hot-only	false	Enables Hot Module Replacement without page refresh as fallback in case of build failures. More information here.
--no-open	false	Do not open automatically the page 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.

important

Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production.

Enabling HTTPS

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

1. Run mkcert localhost to generate localhost.pem + localhost-key.pem

2. Run mkcert -install to install the cert in your trust store, and restart your browser

3. Start the app with Docusaurus HTTPS env variables:

HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start

4. Open https://localhost:3000/

docusaurus build [siteDir]

Compiles your site for production.

Options

Name	Default	Description
--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
--no-minify	false	Build website without minimizing JS/CSS bundles.

info

For advanced minification of CSS bundle, we use the advanced cssnano preset (along with additional several PostCSS plugins) and level 2 optimization of clean-css. If as a result of this advanced CSS minification you find broken CSS, build your website with the environment variable USE_SIMPLE_CSS_MINIFIER=true to minify CSS with the default cssnano preset. Please fill out an issue if you experience CSS minification bugs.

docusaurus swizzle [siteDir]

caution

We discourage swizzling of components during the Docusaurus 2 beta phase. The theme components APIs are likely to evolve and have breaking changes. If possible, stick with the default appearance for now.

Change any Docusaurus theme components to your liking with npm run swizzle.

npm

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

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

Yarn

yarn run swizzle [themeName] [componentName] [siteDir]

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

Running the command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme.

npm run swizzle without themeName lists all the themes available for swizzling; similarly, npm run swizzle <themeName> without componentName lists all the components available for swizzling.

Options

Name	Description
themeName	The name of the theme you are using.
swizzleComponent	The name of the component to swizzle.
--danger	Allow swizzling of unstable components
--typescript	Swizzle TypeScript components

An example to use --danger flag let's consider the below code:

npm

npm run swizzle @docusaurus/theme-classic Logo -- --danger

Yarn

yarn run swizzle @docusaurus/theme-classic Logo -- --danger

caution

Unstable Components: components that have a higher risk of breaking changes due to internal refactorings.

To unswizzle a component, simply delete the files of the swizzled component.

docusaurus deploy [siteDir]

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

Options

Name	Default	Description
--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 custom deploy script.
--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.

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 to add 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.
--maintain-case	false	Keep the headings' casing, otherwise make all lowercase.
--overwrite	false	Overwrite existing heading IDs.