CLI
Docusaurus 提供了帮助你生成并部署网站的脚本。
网站初始化时,就会自带一系列 Docusaurus 脚本,你可以用包管理器调用:
{
// ...
"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
参数 | 默认值 | 描述 |
---|---|---|
--dev | Builds in dev mode, including full React error messages. | |
--port | 3000 | 指定开发服务器端口。 |
--host | localhost | 指定绑定的主机。 For example, if you want your server to be accessible externally, you can use --host 0.0.0.0 . |
--hot-only | false | 在构建失败时,启用无需手动刷新的热模块替换作为后备选项。 More information here. |
--no-open | false | Do not open the page automatically in the browser. |
--config | undefined | Path to Docusaurus config file, default to [siteDir]/docusaurus.config.js |
--poll [optionalIntervalMs] | false | 在无法监听文件系统的环境中,使用文件系统轮询而不是监听作为实时重载的替代方案。 More information here. |
--no-minify | false | 在不压缩 JS/CSS 的情况下构建站点。 |
请注意,某些功能,比如锚点链接,在开发环境中无法使用。 但这些功能会在生产环境中正常工作。
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
Enabling HTTPS
获取证书有很多方法。 We will use mkcert as an example.
-
Run
mkcert localhost
to generatelocalhost.pem
+localhost-key.pem
-
Run
mkcert -install
to install the cert in your trust store, and restart your browser -
添加 Docusaurus HTTPS 环境变量,然后启动应用:
HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
- Open
https://localhost:3000/
docusaurus build [siteDir]
为你的网站做生产构建。
Options
参数 | 默认值 | 描述 |
---|---|---|
--bundle-analyzer | false | Analyze your bundle with the webpack bundle analyzer. |
--out-dir | build | 输出目录的完整路径,相对于当前工作区。 |
--config | undefined | Path to Docusaurus config file, default to [siteDir]/docusaurus.config.js |
--no-minify | false | 在不压缩 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
- Yarn
- pnpm
npm run swizzle [themeName] [componentName] [siteDir]
# 示例(不提供 siteDir 会被自动定向到当前路径)
npm run swizzle @docusaurus/theme-classic Footer -- --eject
yarn swizzle [themeName] [componentName] [siteDir]
# 示例(不提供 siteDir 会被自动定向到当前路径)
yarn swizzle @docusaurus/theme-classic Footer --eject
pnpm run swizzle [themeName] [componentName] [siteDir]
# 示例(不提供 siteDir 会被自动定向到当前路径)
pnpm 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 的组件名 |
--eject | Eject the theme component |
--wrap | Wrap the theme component |
--danger | 允许 swizzle 不安全的组件 |
--typescript | Swizzle TypeScript 组件变种 |
--config | Path 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-dir | build | 输出目录的完整路径,相对于当前工作区。 |
--skip-build | false | 跳过构建直接部署网站。 如果你有自定义的部署脚本,可以用这个选项。 |
--config | undefined | Path to Docusaurus config file, default to [siteDir]/docusaurus.config.js |
docusaurus serve [siteDir]
在本地开启网站服务。
参数 | 默认值 | 描述 |
---|---|---|
--port | 3000 | 使用指定端口。 |
--dir | build | 输出目录相对于当前工作区的完整路径。 |
--build | false | 在开启服务前构建网站。 |
--config | undefined | Path to Docusaurus config file, default to [siteDir]/docusaurus.config.js |
--host | localhost | 指定绑定的主机。 For example, if you want your server to be accessible externally, you can use --host 0.0.0.0 . |
--no-open | false 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 文件的语言文件夹。 |
--override | false | 覆盖现有的翻译内容。 |
--config | undefined | Path 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-case | false | 保留标题的大小写,否则会全部变成小写。 |
--overwrite | false | 覆盖现有的标题 ID。 |