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:
{
// ...
"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 |
---|---|---|
--dev | Builds in dev mode, including full React error messages. | |
--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 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. |
Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production.
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.
- npm
- Yarn
- pnpm
npm run start -- --host 0.0.0.0
yarn run start --host 0.0.0.0
pnpm 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 generatelocalhost.pem
+localhost-key.pem
-
Run
mkcert -install
to install the cert in your trust store, and restart your browser -
Start the app with Docusaurus HTTPS env variables:
HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
- 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. |
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.
You can skip the HTML minification with the environment variable SKIP_HTML_MINIFICATION=true
.
docusaurus swizzle [themeName] [componentName] [siteDir]
Swizzle a theme component to customize it.
- npm
- Yarn
- pnpm
npm run swizzle [themeName] [componentName] [siteDir]
# Example (leaving out the siteDir to indicate this directory)
npm run swizzle @docusaurus/theme-classic Footer -- --eject
yarn swizzle [themeName] [componentName] [siteDir]
# Example (leaving out the siteDir to indicate this directory)
yarn swizzle @docusaurus/theme-classic Footer --eject
pnpm run swizzle [themeName] [componentName] [siteDir]
# Example (leaving out the siteDir to indicate this directory)
pnpm run swizzle @docusaurus/theme-classic Footer --eject
The swizzle CLI is interactive and will guide you through the whole swizzle process.