跳到主要内容

命令行工具(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 在本地构建并提供站点的预览。

参数列表

名称默认值描述
--port3000Specifies the port of the dev server.
--hostlocalhostSpecify a host to use. For example, if you want your server to be accessible externally, you can use --host 0.0.0.0.
--hot-onlyfalseEnables Hot Module Replacement without page refresh as a fallback in case of build failures. More information here.
--no-openfalseDo not open automatically the page in the browser.
--configundefinedPath to docusaurus config file, default to [siteDir]/docusaurus.config.js
--poll [optionalIntervalMs]falseUse polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information here.
--no-minifyfalseBuild website without minimizing JS/CSS bundles.
important

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

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 run start -- --host 0.0.0.0

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

Swizzle a theme component to customize it.

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

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

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

Options

名称描述
themeNameThe name of the theme to swizzle from.
componentNameThe name of the theme component to swizzle.
--listDisplay components available for swizzling
--ejectEject the theme component
--wrapWrap the theme component
--dangerAllow immediate swizzling of unsafe components
--typescriptSwizzle the TypeScript variant component
caution

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

docusaurus deploy [siteDir]

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

参数列表

名称默认值描述
--out-dirbuildThe full path for the new output directory, relative to the current workspace.
--skip-buildfalseDeploy website without building it. This may be useful when using a custom deploy script.
--configundefinedPath to docusaurus config file, default to [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
--no-open本地开发环境中默认值是 false;CI(持续集成)环境中默认值是 true不要启动浏览器窗口并打开网站。

docusaurus clear [siteDir]

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

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

docusaurus write-translations [siteDir]

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

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

名称默认值描述
--locale<defaultLocale>Define which locale folder you want to write translations the JSON files in
--overridefalseOverride existing translation messages
--configundefinedPath to docusaurus config file, default to [siteDir]/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

NameDefaultDescription
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.