跳到主要内容
版本:2.4.3

CLI

Docusaurus 提供了帮助你生成并部署网站的脚本。

网站初始化时,就会自带一系列 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 commands

下方是 Docusaurus CLI 命令及用法列表:

docusaurus start [siteDir]

Builds and serves a preview of your site locally with Webpack Dev Server.

Options

参数默认值描述
--port3000指定开发服务器端口。
--hostlocalhost指定绑定的主机。 For example, if you want your server to be accessible externally, you can use --host 0.0.0.0.
--hot-onlyfalse在构建失败时,启用无需手动刷新的热模块替换作为后备选项。 More information here.
--no-openfalse不在浏览器中自动打开页面。
--configundefinedPath to Docusaurus config file, default to [siteDir]/docusaurus.config.js
--poll [optionalIntervalMs]false在无法监听文件系统的环境中,使用文件系统轮询而不是监听作为实时重载的替代方案。 More information here.
--no-minifyfalse在不压缩 JS/CSS 的情况下构建站点。
信息

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

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

获取证书有很多方法。 We will use mkcert as an example.

  1. Run mkcert localhost to generate localhost.pem + localhost-key.pem

  2. Run mkcert -install to install the cert in your trust store, and restart your browser

  3. 添加 Docusaurus HTTPS 环境变量,然后启动应用:

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

docusaurus build [siteDir]

为你的网站做生产构建。

Options

参数默认值描述
--bundle-analyzerfalseAnalyze your bundle with the webpack bundle analyzer.
--out-dirbuild输出目录的完整路径,相对于当前工作区。
--configundefinedPath to Docusaurus config file, default to [siteDir]/docusaurus.config.js
--no-minifyfalse在不压缩 JS/CSS 的情况下构建站点。
信息

For advanced minification of CSS bundle, we use the advanced cssnano preset (along with additional several PostCSS plugins) and level 2 optimization of clean-css. If as a result of this advanced CSS minification you find broken CSS, build your website with the environment variable USE_SIMPLE_CSS_MINIFIER=true to minify CSS with the default cssnano preset. Please fill out an issue if you experience CSS minification bugs.

You can skip the HTML minification with the environment variable SKIP_HTML_MINIFICATION=true.

docusaurus swizzle [themeName] [componentName] [siteDir]

Swizzle a theme component to customize it.

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

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

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

Options

参数描述
themeName要 swizzle 的主题名。
componentName要 swizzle 的主题组件名。
--list显示所有可 swizzle 的组件名
--ejectEject the theme component
--wrapWrap the theme component
--danger允许 swizzle 不安全的组件
--typescriptSwizzle TypeScript 组件变种
--configPath to docusaurus config file, default to [siteDir]/docusaurus.config.js
注意

不安全组件很容易因为内部重构而产生破坏性变更。

docusaurus deploy [siteDir]

Deploys your site with GitHub Pages. Check out the docs on deployment for more details.

Options

参数默认值描述
--out-dirbuild输出目录的完整路径,相对于当前工作区。
--skip-buildfalse跳过构建直接部署网站。 如果你有自定义的部署脚本,可以用这个选项。
--configundefinedPath to Docusaurus config file, default to [siteDir]/docusaurus.config.js

docusaurus serve [siteDir]

在本地开启网站服务。

参数默认值描述
--port3000使用指定端口。
--dirbuild输出目录相对于当前工作区的完整路径。
--buildfalse在开启服务前构建网站。
--configundefinedPath to Docusaurus config file, default to [siteDir]/docusaurus.config.js
--hostlocalhost指定绑定的主机。 For example, if you want your server to be accessible externally, you can use --host 0.0.0.0.
--no-openfalse locally, true in CI不要打开浏览器窗口。

docusaurus clear [siteDir]

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

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

docusaurus write-translations [siteDir]

写入 JSON 翻译文件,你需要翻译它们。

By default, the files are written in website/i18n/<defaultLocale>/....

参数默认值描述
--locale<defaultLocale>定义你想要写入 JSON 文件的语言文件夹。
--overridefalse覆盖现有的翻译内容。
--configundefinedPath to Docusaurus config file, default to [siteDir]/docusaurus.config.js
--messagePrefix''允许为每个翻译信息添加一个前缀,以突出显示未翻译的字符串。

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

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

参数默认值描述
files所有被插件使用的 MD 文件你想要写入标题 ID 的文件。
--maintain-casefalse保留标题的大小写,否则会全部变成小写。
--overwritefalse覆盖现有的标题 ID。