CLI
Docusaurus 提供了一组脚本来帮助你生成、服务和部署网站。
¥Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.
一旦你的网站启动,网站源代码将包含 Docusaurus 脚本,你可以使用包管理器调用这些脚本:
¥Once your website is bootstrapped, the website source will contain the Docusaurus scripts that you can invoke with your package manager:
{
// ...
"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 commands
以下是 Docusaurus CLI 命令及其用法的列表:
¥Below is a list of Docusaurus CLI commands and their usages:
docusaurus start [siteDir]
使用 Webpack 开发服务器 在本地构建并提供站点预览。
¥Builds and serves a preview of your site locally with Webpack Dev Server.
选项
¥Options
名称 | 默认 | 描述 |
---|---|---|
--port | 3000 | 指定开发服务器的端口。 |
--host | localhost | 指定要使用的主机。例如,如果你希望外部可以访问你的服务器,则可以使用 --host 0.0.0.0 。 |
--locale | 指定要使用的站点区域设置。 | |
--hot-only | false | 启用热模块替换,无需刷新页面,作为构建失败时的后备方案。更多信息 此处。 |
--no-open | false | 不要在浏览器中自动打开页面。 |
--config | undefined | Docusaurus 配置文件的路径,默认为 [siteDir]/docusaurus.config.js |
--poll [optionalIntervalMs] | false | 使用文件轮询而不是监视实时重新加载,作为监视不起作用的环境中的后备措施。更多信息 此处。 |
--no-minify | false | 在不最小化 JS/CSS 打包的情况下构建网站。 |
请注意,某些功能(例如锚链接)在开发中将无法使用。该功能将在生产中按预期工作。
¥Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production.
当从远程服务器或虚拟机(例如 GitHub Codespaces)转发端口 3000 时,你可以在 0.0.0.0
上运行开发服务器以使其监听本地 IP。
¥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
- Yarn
- pnpm
npm run start -- --host 0.0.0.0
yarn run start --host 0.0.0.0
pnpm run start --host 0.0.0.0
启用 HTTPS
¥Enabling HTTPS
获得证书的方法有多种。我们将以 mkcert 为例。
¥There are multiple ways to obtain a certificate. We will use mkcert as an example.
-
运行
mkcert localhost
生成localhost.pem
+localhost-key.pem
¥Run
mkcert localhost
to generatelocalhost.pem
+localhost-key.pem
-
运行
mkcert -install
将证书安装到你的信任存储中,然后重新启动浏览器¥Run
mkcert -install
to install the cert in your trust store, and restart your browser -
使用 Docusaurus HTTPS 环境变量启动应用:
¥Start the app with Docusaurus HTTPS env variables:
HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
-
打开
https://localhost:3000/
¥Open
https://localhost:3000/
docusaurus build [siteDir]
编译你的网站以进行生产。
¥Compiles your site for production.
选项
¥Options
名称 | 默认 | 描述 |
---|---|---|
--dev | 在开发模式下构建网站,包括完整的 React 错误消息。 | |
--bundle-analyzer | false | 使用 webpack 打包分析器 分析你的打包包。 |
--out-dir | build | 新输出目录相对于当前工作区的完整路径。 |
--config | undefined | Docusaurus 配置文件的路径,默认为 [siteDir]/docusaurus.config.js |
--locale | 在指定的区域设置中构建站点。如果未指定,则构建所有已知的语言环境。 | |
--no-minify | false | 在不最小化 JS/CSS 打包的情况下构建网站。 |
为了对 CSS 包进行高级缩小,我们使用 高级 cssnano 预设(以及其他几个 PostCSS 插件)和 clean-css 的 2 级优化。如果由于这种高级 CSS 缩小,你发现 CSS 损坏,请使用环境变量 USE_SIMPLE_CSS_MINIFIER=true
构建你的网站,以使用 默认 cssnano 预设 缩小 CSS。如果你遇到 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.
你可以使用环境变量 SKIP_HTML_MINIFICATION=true
跳过 HTML 缩小。
¥You can skip the HTML minification with the environment variable SKIP_HTML_MINIFICATION=true
.
docusaurus swizzle [themeName] [componentName] [siteDir]
Swizzle 一个主题组件来定制它。
¥Swizzle a theme component to customize it.
- npm
- Yarn
- pnpm
npm run swizzle [themeName] [componentName] [siteDir]
# Example (leaving out the siteDir to indicate this directory)
npm run swizzle @docusaurus/theme-classic Footer -- --eject
yarn swizzle [themeName] [componentName] [siteDir]
# Example (leaving out the siteDir to indicate this directory)
yarn swizzle @docusaurus/theme-classic Footer --eject
pnpm run swizzle [themeName] [componentName] [siteDir]
# Example (leaving out the siteDir to indicate this directory)
pnpm run swizzle @docusaurus/theme-classic Footer --eject
swizzle CLI 是交互式的,将指导你完成整个 调配过程。
¥The swizzle CLI is interactive and will guide you through the whole swizzle process.
选项
¥Options
名称 | 描述 |
---|---|
themeName | 要混合的主题的名称。 |
componentName | 要混合的主题组件的名称。 |
--list | 可用于调配的显示组件 |
--eject | Eject 主题组件 |
--wrap | 裹 主题组件 |
--danger | 允许立即混合不安全的组件 |
--typescript | Swizzle TypeScript 变体组件 |
--config | docusaurus 配置文件的路径,默认为 [siteDir]/docusaurus.config.js |
由于内部重构,不安全的组件发生破坏性变更的风险更高。
¥Unsafe components have a higher risk of breaking changes due to internal refactorings.
docusaurus deploy [siteDir]
使用 GitHub 页面 部署你的站点。查看 deployment 上的文档了解更多详细信息。
¥Deploys your site with GitHub Pages. Check out the docs on deployment for more details.
选项
¥Options
名称 | 默认 | 描述 |
---|---|---|
--locale | 在指定的区域设置中部署站点。如果未指定,则部署所有已知区域设置。 | |
--out-dir | build | 新输出目录相对于当前工作区的完整路径。 |
--skip-build | false | 部署网站而不构建它。使用自定义部署脚本时这可能很有用。 |
--target-dir | . | 要部署到的目标目录的路径。 |
--config | undefined | Docusaurus 配置文件的路径,默认为 [siteDir]/docusaurus.config.js |
docusaurus serve [siteDir]
在本地提供你构建的网站。
¥Serve your built website locally.
名称 | 默认 | 描述 |
---|---|---|
--port | 3000 | 使用指定端口 |
--dir | build | 输出目录相对于当前工作区的完整路径 |
--build | false | 服务前先建立网站 |
--config | undefined | Docusaurus 配置文件的路径,默认为 [siteDir]/docusaurus.config.js |
--host | localhost | 指定要使用的主机。例如,如果你希望外部可以访问你的服务器,则可以使用 --host 0.0.0.0 。 |
--no-open | 本地 false ,CI true | 不要打开服务器位置的浏览器窗口。 |
docusaurus clear [siteDir]
清除 Docusaurus 站点生成的资源、缓存、构建工件。
¥Clear a Docusaurus site's generated assets, caches, build artifacts.
我们建议在报告错误之前、升级版本之后或在 Docusaurus 站点出现问题时运行此命令。
¥We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site.
docusaurus write-translations [siteDir]
编写你需要翻译的 JSON 翻译文件。
¥Write the JSON translation files that you will have to translate.
默认情况下,文件以 website/i18n/<defaultLocale>/...
写入。
¥By default, the files are written in website/i18n/<defaultLocale>/...
.
名称 | 默认 | 描述 |
---|---|---|
--locale | <defaultLocale> | 定义要在其中写入 JSON 文件翻译的语言环境文件夹 |
--override | false | 覆盖现有翻译消息 |
--config | undefined | Docusaurus 配置文件的路径,默认为 [siteDir]/docusaurus.config.js |
--messagePrefix | '' | 允许为每条翻译消息添加前缀,以帮助你高亮未翻译的字符串 |
docusaurus write-heading-ids [siteDir] [files]
将 显式标题 ID 添加到你网站的 Markdown 文档中。
¥Add explicit heading IDs to the Markdown documents of your site.
名称 | 默认 | 描述 |
---|---|---|
files | 插件使用的所有 MD 文件 | 你想要写入标题 ID 的文件。 |
--maintain-case | false | 保留标题的大小写,否则全部小写。 |
--overwrite | false | 覆盖现有的标题 ID。 |