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

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-onlyfalseEnables Hot Module Replacement without page refresh as a fallback in case of build failures. 详情参见此处
--no-openfalse不在浏览器中自动开启页面。
--configundefinedDocusaurus 配置文件的路径,默认为 [站点目录]/docusaurus.config.js
--poll [optionalIntervalMs]false在监听不起作用的环境中,使用文档轮询而不是监听作为实时重载的替代方案。 更多信息,请参见这里
important

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

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

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

选项

参数描述
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-dirbuild输出目录的完整路径,与当前工作区相对。
--skip-buildfalse部署网站而不构建它。 This may be useful when using a custom deploy script.
--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''Allows adding a prefix to each translation message, to help you highlight untranslated strings

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

Add explicit heading ids to the Markdown documents of your site.

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