跳到主要内容

命令行工具(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 [siteDir]#

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

参数列表#

名称默认值描述
--port3000指定开发服务器监听的端口。
--hostlocalhost指定要使用的主机。例如,如果希望服务器可以从外部访问,则可以使用 --host 0.0.0.0
--hot-onlyfalse在构建失败的情况下,启用热模块替换而不进行页面刷新的方式作为后备。更多信息请见 这里
--no-openfalse不要在浏览器中自动打开页面。
--configundefined指向 docusaurus 配置文件的路径,默认为 [siteDir]/docusaurus.config.js
--poll [optionalIntervalMs]false在文件监视(watching)功能不能工作的环境中,使用文件轮询(polling)而不是监视(watching)的功能实现实时重新加载。 更多信息请见 这里
important

请注意,某些功能(例如 anchor 链接)在开发环境中将无法使用,但在生产环境中能正常工作。

启用 HTTPS#

有多种获取 SSL 证书的方法。我们将以 mkcert 为例。

  1. 运行 mkcert localhost 命令生成 localhost.pem + localhost-key.pem

  2. 运行 mkcert -install 将证书安装到您信任的库(store)中,然后重启浏览器

  3. 设置 HTTPS 环境变量并启动应用程序:

HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
  1. 在浏览器中打开 https://localhost:3000/ 地址

docusaurus build [siteDir]#

为生产环境编译网站。

参数列表#

名称默认值描述
--bundle-analyzerfalse利用 webpack bundle analyzer 分析所打的包。
--out-dirbuild相对于当前工作空间的新输出目录的完整路径。
--configundefined指向 docusaurus 配置文件的路径,默认为 [siteDir]/docusaurus.config.js
--no-minifyfalse构建网站并且不对 JS/CSS 包进行压缩。
info

为了让 CSS 包达到更好的压缩效果,我们使用的是 cssnano 高级预设 (和其它几个 PostCSS 插件) 以及 clean-css 的 level 2 等级的优化。如果由于此 CSS 压缩设置导致您的 CSS 损坏,请在构建按网站时设置环境变量 USE_SIMPLE_CSS_MINIFIER=true 从而使用 cssnano 的默认预设 来压缩 CSS。如果您遇到 CSS 压缩方面的 bug,请 提交问题报告 给我们。

docusaurus swizzle [siteDir]#

caution

在进入 Beta 阶段之前,我们强烈建议不要使用组件覆盖(swizzling of components)功能。由于组件的 API 一直在快速变化,并且可能会不断变化,直到我们达到 Beta 版本位置。如果可能的话,现阶段请使用默认外观,以免将来遭受潜在的痛苦。

根据自己的喜好,利用 npm run swizzle 可以更改 Docusaurus 主题的任何组件。

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

运行该命令会将相关主题文件复制到您的站点文件夹中。然后,您可以对其进行任何更改,Docusaurus 将使用修改过的版本而不是主题自带的内容。

如果运行 npm run swizzle 命令时未指定 themeName,则会列出所有可被覆盖(swizzling)的主题;同样的,而如果运行 npm run swizzle <themeName> 命令时未指定 componentName 则会列出所有可被覆盖(swizzling)的组件。

参数列表#

名称描述
themeName正在使用的主题的名称。
swizzleComponent需要覆盖(swizzling)的组件的名称。
--danger允许覆盖(swizzling)非稳定版本的组件
--typescript覆盖(swizzling) TypeScript 组件

使用 --danger 标志的示例如下:

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

非稳定版本的组件(Unstable Components):指由于内部重构而具有较大不兼容风险的组件。

如需取消自定义组件,只需删除自定义组件所对应的文件即可。

docusaurus deploy [siteDir]#

如需将站点部署到 GitHub Pages 上,请查看 部署 章节的文档以了解更多信息。

参数列表#

名称默认值描述
--out-dirbuild相对于当前工作空间的新输出目录的完整路径。
--skip-buildfalse略过构建步骤并部署网站。 使用自定义部署脚本时会很有用。
--configundefined指定 docusaurus 配置文件的路径,默认为 [siteDir]/docusaurus.config.js

docusaurus serve [siteDir]#

为构建后的网站启动 web 服务器。

参数名默认值描述信息
--port3000使用指定的端口号
--dirbuild输出目录的完整路径(相对于当前工作空间)
--buildfalse在启动 web 服务器前先构建网站
--configundefined指向 docusaurus 配置文件的路径,默认为 [siteDir]/docusaurus.config.js
--hostlocalhost指定要使用的主机。例如,如果您希望启动的 web 服务器能够从外部被访问,则可以指定 --host 0.0.0.0

docusaurus clear [siteDir]#

清除 Docusaurus 站点在构建时生成的静态资源、缓存、副产品。

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

docusaurus write-translations [siteDir]#

将需要翻译的内容写入 JSON 文件中。

默认情况下,该文件将被写入 website/i18n/<defaultLocale>/... 目录中。

名称默认值描述
--locale<defaultLocale>定义本地化语言所对应的目录,并将用于翻译的 JSON 文件写入其中
--overridefalse覆盖已经翻译的消息
--configundefineddocusaurus 配置文件的路径,默认为 [siteDir]/docusaurus.config.js
--messagePrefix''为每条待翻译的消息前添加前缀,以帮助你突出显示未翻译的字符串

docusaurus write-heading-ids [siteDir]#

为站点的 Markdown 文档显式地添加 标题的 id