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

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

选项

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

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

Enabling 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 [站点目录]

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

选项

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

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

docusaurus swizzle [siteDir]

caution

我们暂不建议在 Docusaurus 2 Beta 阶段进行组件变换(Swizzling)。 主题组件 API 随时有可能迭代,且随时可能进行重大修改。 若无特别需要,我们强烈建议您继续使用默认的外观。

使用 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 的组件。

选项

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

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

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

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

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

docusaurus deploy [siteDir]

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

选项

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

docusaurus serve [siteDir]

在本地开启网站服务。

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

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

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

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

参数默认值描述
filesAll MD files used by pluginsThe files that you want heading IDs to be written to.
--maintain-casefalseKeep the headings' casing, otherwise make all lowercase.
--overwritefalseOverwrite existing heading IDs.