CLI

Docusaurus 提供了帮助您生成并部署网站的脚本。

当您的网站初始化完毕时，您可使用包管理器运行自带的脚本：

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 命令

下方是 Docusaurus CLI 命令及用法列表：

docusaurus start [站点目录]

构建并在本地使用 Webpack 开发服务器部署站点预览：

选项

参数	默认值	描述
--port	3000	指定开发服务器端口。
--host	localhost	指定绑定的主机。 例如，若您想让开发服务器可被外部访问，您可使用参数 --host 0.0.0.0。
--hot-only	false	Enables Hot Module Replacement without page refresh as a fallback in case of build failures. 详情参见此处。
--no-open	false	不在浏览器中自动开启页面。
--config	undefined	Docusaurus 配置文件的路径，默认为 [站点目录]/docusaurus.config.js
--poll [optionalIntervalMs]	false	在监听不起作用的环境中，使用文档轮询而不是监听作为实时重载的替代方案。 更多信息，请参见这里。

important

请注意，某些如锚点链接的功能在开发环境中无法使用。 但这些功能将在生产环境中正常工作。

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

npm run start -- --host 0.0.0.0

Yarn

yarn run start -- --host 0.0.0.0

Enabling HTTPS

您有多种方式获取证书。 本例中，我们将使用 mkcert。

1. 运行 mkcert localhost 来生成 localhost.pem 及 localhost-key.pem

2. 运行 mkcert -install 以安装证书至您的受信存储，然后请重启浏览器。

3. 使用 Docusaurus HTTPS 环境变量开启应用程序：

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

4. 打开 https://localhost:3000/

docusaurus build [站点目录]

为生产环境编译您的网站。

选项

参数	默认值	描述
--bundle-analyzer	false	使用 Webpack Bundle Analyzer 分析您的软件包。
--out-dir	build	输出目录的完整路径，与当前工作区相对。
--config	undefined	Docusaurus 配置文件的路径，默认为 [站点目录]/docusaurus.config.js
--no-minify	false	在不压缩 JS/CSS 的情况下构建站点。

信息

我们使用 cssnano 进阶配置（搭配其他几个 PostCSS 插件）以及 clean-css 2 级优化来进阶精简 CSS。 若您的 CSS 由于进阶精简功能而无法使用，您可使用环境变量 USE_Sibon_CSS_MINIFIER=true 来构建你的网站，此选项使用 默认的 cssnano 预设来精简 CSS。 如果你遇到 CSS 最小化的 bug，请提交一个 issue。

docusaurus swizzle [themeName] [componentName] [siteDir]

Swizzle a theme component to customize it.

npm

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

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

Yarn

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

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

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

选项

参数	描述
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

caution

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

docusaurus deploy [siteDir]

使用 GitHub Pages 部署你的网站。 查看部署文档以了解详情。

选项

参数	默认值	描述
--out-dir	build	输出目录的完整路径，与当前工作区相对。
--skip-build	false	部署网站而不构建它。 This may be useful when using a custom deploy script.
--config	undefined	Docusaurus 配置文件的路径，默认为 [站点目录]/docusaurus.config.js

docusaurus serve [siteDir]

在本地开启网站服务。

参数	默认值	描述
--port	3000	使用指定端口。
--dir	build	输出目录相对于当前工作区的完整路径。
--build	false	在开启服务前构建网站。
--config	undefined	Docusaurus 配置文件的路径，默认为 [站点目录]/docusaurus.config.js
--host	localhost	指定绑定的主机。 例如，若您想让开发服务器可被外部访问，您可使用参数 --host 0.0.0.0。

docusaurus clear [siteDir]

清除 Docusaurus 网站生成的资源、缓存、构建产物。

我们建议在报告 bug 之前、在升级版本之后，或在你使用 Docusaurus 网站遇到任何问题时运行此命令。

docusaurus write-translations [siteDir]

写入您需要翻译的 JSON 翻译文件。

默认情况下，文件会被写入 website/i18n/<defaultLocale>/...。

参数	默认值	描述
--locale	<defaultLocale>	定义你想要写入 JSON 文件的区域文件夹。
--override	false	覆盖现有的翻译内容。
--config	undefined	Docusaurus 配置文件的路径，默认为 [站点目录]/docusaurus.config.js
--messagePrefix	''	Allows adding a prefix to each translation message, to help you highlight untranslated strings

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

为你的网站的 Markdown 文档添加显式的标题 id。

参数	默认值	描述
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.