Skip to content

Latest commit

 

History

History
185 lines (126 loc) · 8.33 KB

cli.md

File metadata and controls

185 lines (126 loc) · 8.33 KB
Raw
description
Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.

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 {#docusaurus-cli-commands}

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

docusaurus start [siteDir] {#docusaurus-start-sitedir}

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

Options {#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 a 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.
--no-minify false Build website without minimizing JS/CSS bundles.

:::important

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

:::

:::info 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.

npm run start -- --host 0.0.0.0

:::

Enabling HTTPS {#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
  1. Open https://localhost:3000/

docusaurus build [siteDir] {#docusaurus-build-sitedir}

Compiles your site for production.

Options {#options-1}

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.

You can skip the HTML minification with the environment variable SKIP_HTML_MINIFICATION=true.

:::

docusaurus swizzle [themeName] [componentName] [siteDir] {#docusaurus-swizzle}

Swizzle a theme component to customize it.

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 {#options-swizzle}

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
--config Path to docusaurus config file, default to [siteDir]/docusaurus.config.js

:::caution

Unsafe components have a higher risk of breaking changes due to internal refactorings.

:::

docusaurus deploy [siteDir] {#docusaurus-deploy-sitedir}

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

Options {#options-3}

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 a custom deploy script.
--config undefined Path to Docusaurus config file, default to [siteDir]/docusaurus.config.js

docusaurus serve [siteDir] {#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] {#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] {#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] {#docusaurus-write-heading-ids-sitedir}

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.