跳转至主内容
Version: 2.0.0-beta.0

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 开发服务器部署站点预览:

选项#

Name默认值Description
--port3000指定开发服务器端口。
--hostlocalhost指定绑定的主机。 例如,若您想让开发服务器可被外部访问,您可使用参数 --host 0.0.0.0
--hot-onlyfalse在构建失败时,启用无需手动刷新的热模块替换作为后备选项。 详情参见此处
--no-openfalse不在浏览器中自动开启页面。
--configundefinedDocusaurus 配置文件的路径,默认为 [站点目录]/docusaurus.config.js
--poll [optionalIntervalMs]false在监听不起作用的环境中,使用文档轮询而不是监听作为实时重载的替代方案。 更多信息,请参见这里
important

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

启用 HTTPS#

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

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

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

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

HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
  1. 打开 https://localhost:3000/

docusaurus build [站点目录]#

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

选项#

Name默认值Description
--bundle-analyzerfalse使用 Webpack Bundle Analyzer 分析您的软件包。
--out-dirbuild输出目录的完整路径,与当前工作区相对。
--configundefinedDocusaurus 配置文件的路径,默认为 [站点目录]/docusaurus.config.js
--no-minifyfalse在不压缩 JS/CSS 的情况下构建站点。
info

对于 CSS 打包的高级缩小化,我们使用高级 cssnano 配置(和其他的几个 PostCSS 插件搭配)以及 clean-css 2 级优化。 如果由于高级 CSS 缩小化,你发现 CSS 被损坏,可以使用环境变量 USE_Sibon_CSS_MINIFIER=true 来构建你的网站,以使用 默认的 cssnano 预设来缩小 CSS。 如果你遇到 CSS 最小化的 bug,请提交一个 issue

docusaurus swizzle [siteDir]#

caution

We discourage swizzling of components during the Docusaurus 2 beta phase. The theme components APIs are likely to evolve and have breaking changes. If possible, stick with the default appearance for now.

使用 npm run swizzle 更改任何你中意的 Docusaurus 主题组件。

npm run swizzle [themeName] [componentName] [siteDir]
# 示例(不提供 siteDir 会被自动定向到当前路径)
npm run swizzle @docusaurus/theme-classic DocSidebar

运行该命令会把相关的主题文件复制到你的网站文件夹。 你可以对它做任何更改,然后 Docusaurus 就会使用它,而不是主题中提供的那个。

如果 npm run swizzle 不包含 themeName,它就会列出所有可用的主题;同样,npm run swizzle <themeName> 如果不包含 components,就会列出所有可供 swizzle 的组件。

选项#

NameDescription
themeName你所使用的主题名。
swizzleComponent要 swizzle 的组件名。
--danger允许 swizzle 不稳定的组件。
--typescriptSwizzle Typescript 组件。

举个 --danger 的例子,我们考虑以下代码:

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

不稳定组件:指那些很容易因内部重构而产生破坏性变更的组件。

要终止组件 swizzle,只需要删除被 swizzle 的组件的文件。

docusaurus deploy [siteDir]#

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

选项#

Name默认值Description
--out-dirbuild输出目录的完整路径,与当前工作区相对。
--skip-buildfalse部署网站而不构建它。 使用自定义部署脚本时可能有用。
--configundefinedDocusaurus 配置文件的路径,默认为 [站点目录]/docusaurus.config.js

docusaurus serve [siteDir]#

在本地开启网站服务。

Name默认值Description
--port3000使用指定端口。
--dirbuild输出目录相对于当前工作区的完整路径。
--buildfalse在开启服务前构建网站。
--configundefinedDocusaurus 配置文件的路径,默认为 [站点目录]/docusaurus.config.js
--hostlocalhost指定绑定的主机。 例如,若您想让开发服务器可被外部访问,您可使用参数 --host 0.0.0.0

docusaurus clear [siteDir]#

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

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

docusaurus write-translations [siteDir]#

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

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

Name默认值Description
--locale<defaultLocale>定义你想要写入 JSON 文件的区域文件夹。
--overridefalse覆盖现有的翻译内容。
--configundefinedDocusaurus 配置文件的路径,默认为 [站点目录]/docusaurus.config.js
--messagePrefix''允许为每个翻译信息添加一个前缀,以突出显示未翻译的字符串。

docusaurus write-heading-ids [siteDir]#

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