CLI

Docusaurus 提供了一组脚本来帮助您生成、服务和部署您的网站。

一旦你的网站被引导，网站源代码将包含 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 [siteDir]

使用Webpack Dev Server在本地构建并提供网站预览。

Options

名字	默认	描述
--dev		在开发模式下构建，包括完整的 React 错误消息。
--port	3000	开发服务器的端口。
--host	localhost	指定要使用的主机。例如，如果你想让你的服务器可以被外部访问，你可以使用——host 0.0.0.0。
--hot-only	false	在构建失败的情况下，启用热模块替换而不刷新页面作为回退。更多信息请点击这里。
--no-open	false	不要在浏览器中自动打开该页面。
--config	undefined	Docusaurus 配置文件的路径，默认为[siteDir]/docusaurus.config.js
--poll [optionalIntervalMs]	false	在监视不起作用的环境中，使用文件轮询而不是监视实时重新加载作为备用方案。更多信息请点击这里。
--no-minify	false	在不减少 JS/CSS 包的情况下构建网站。

important

请注意，某些功能(例如，锚链接)将无法在开发中工作。该功能将在生产中按预期工作。

网络开发

当从远程服务器或 VM(例如 GitHub Codespaces)转发端口 3000 时，您可以在0.0.0.0上运行开发服务器，使其侦听本地 IP。

npm

npm run start -- --host 0.0.0.0

Yarn

yarn run start --host 0.0.0.0

pnpm

pnpm run start -- --host 0.0.0.0

启用 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 [siteDir]

编译您的网站用于生产。

选项

名字	默认	描述
--bundle-analyzer	false	使用webpack bundle 分析器分析你的 bundle.
--out-dir	build	相对于当前工作区，新输出目录的完整路径。
--config	undefined	Docusaurus 配置文件的路径，默认为[siteDir]/docusaurus.config.js
--no-minify	false	在不减少 JS/CSS 包的情况下构建网站。

信息

对于 CSS 包的高级缩小，我们使用高级 cssnano 预设(以及额外的几个 PostCSS 插件)和clean-css 的二级优化。 如果作为这个先进的 CSS 缩小的结果，你发现破碎的 CSS，用环境变量USE_SIMPLE_CSS_MINIFIER=true来构建你的网站，用默认的 cssnano 预设来缩小 CSS。 如果您遇到 CSS 最小化错误，请填写问题

您可以使用环境变量SKIP_HTML_MINIFICATION=true跳过 HTML 缩小。

docusaurus swizzle [themeName] [componentName] [siteDir]

Swizzle一个主题组件来定制它。

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 swizzle [themeName] [componentName] [siteDir]

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

pnpm

pnpm run swizzle [themeName] [componentName] [siteDir]

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

swizzle 命令行是交互式的，将指导您完成整个swizzle 过程。

选项

名字	描述
themeName	要搅拌的主题的名称。
componentName	要搅拌的主题组件的名称。
--list	显示可用于搅拌的组件
--eject	Eject 主题组件
--wrap	Wrap 主题组件
--danger	允许不安全部件立即搅拌
--typescript	搅拌 TypeScript 变体组件
--config	docusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js

警告

由于内部重构，不安全的组件有更高的破坏更改的风险。

docusaurus deploy [siteDir]

部署您的网站与GitHub 页面。查看部署上的文档了解更多细节。

选项

名字	默认	描述
--out-dir	build	相对于当前工作区，新输出目录的完整路径。
--skip-build	false	部署网站而不构建它。在使用自定义部署脚本时，这可能很有用。
--config	undefined	Docusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js

docusaurus serve [siteDir]

为你在当地建立的网站服务。

名字	默认	描述
--port	3000	使用指定端口
--dir	build	输出目录的完整路径，相对于当前工作区
--build	false	先建网站再服务
--config	undefined	Docusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--host	localhost	指定要使用的主机。例如，如果您希望从外部访问您的服务器，您可以使用 --host 0.0.0.0.
--no-open	false locally, true in CI	不要打开服务器位置的浏览器窗口。

docusaurus clear [siteDir]

清除一个 Docusaurus 站点生成的资产，缓存，构建工件

我们建议在报告错误之前、升级版本之后或任何时候您的 Docusaurus 站点出现问题之前运行此命令。

docusaurus write-translations [siteDir]

编写需要翻译的 JSON 翻译文件。

默认情况下，将文件写入 website/i18n/<defaultLocale>/... 中.

名字	默认	描述
--locale	<defaultLocale>	定义要在哪个区域设置文件夹中写入 JSON 文件的翻译
--override	false	覆盖现有的翻译消息
--config	undefined	Docusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--messagePrefix	''	允许为每个翻译消息添加前缀，以帮助您突出显示未翻译的字符串

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

添加明确的标题 IDs到你网站的 Markdown 文档。

名字	默认	描述
files	All MD files used by plugins	您希望将标题 id 写入的文件。
--maintain-case	false	保持标题的大小写，否则全部小写。
--overwrite	false	覆盖现有的标题 id。