安装流程
Docusaurus 本质上是一组 npm包。
用 Fast Track 在 **5 分钟 ⏱**内了解 Docusaurus!
用 docusaurus.new 在浏览器中即刻体验 Docusaurus!
要求
- Node.js 版本 18.0 或以上 (可以通过运行
node -v
来查看)。 你可以用 nvm 来管理同一机器上的多个 Node 版本。- 安装 Node.js 时,建议勾选所有和依赖相关的选项。
项目脚手架
使用命令行工具可以帮助你快速简单地安装 Docusaurus 并搭建网站框架。 你可以在空仓库或现有仓库的任何地方运行这个命令,它会创建一个包含模板文件的新目录。
npx create-docusaurus@latest my-website classic
推荐使用 classic
模板来快速上手,同时它也包含 Docusaurus 1 中的功能。 classic
模板内含 @docusaurus/preset-classic
包,后者包含了标准文档、博客、自定义页面及 CSS 框架(支持暗黑模式)。 你可以用经典模板来快速设立网站,在熟悉了 Docusaurus 之后,再逐步对其自定义。
你也可以用 --typescript
选项来使用模板的 TypeScript 变种。 更多详情请查看 Typescript 支持。
npx create-docusaurus@latest my-website classic --typescript
如果你正在为 Meta 开源项目建立 Docusaurus 站点,请在项目中运行以下命令,这可以启用一些 Meta 专用的配置。
scarf static-docs-bootstrap
其他安装指令
你也可以用你喜欢的包管理器来初始化新项目:
- npm
- Yarn
- pnpm
npm init docusaurus
yarn create docusaurus
pnpm create docusaurus
运行 npx create-docusaurus@latest --help
, 或者查看 API 文档 以了解更多可用选项
项目结构
假设你选择了经典模板并将网站命名为 my-website
,你将会在新目录 my-website/
下看到下列文件:
my-website
├── blog
│ ├── 2019-05-28-hola.md
│ ├── 2019-05-29-hello-world.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock
项目结构解读
/blog/
- 包含博客的 Markdown 文件。 如果你后续禁用了博客插件,你可以删除这个目录,或者你也可以在设置path
选项之后修改它的名称。 详情可参考博客指南/docs/
- 包含文档的 Markdown 文件。 你可以在sidebars.js
中自定义文档的侧边栏顺序。 如果你后续禁用了文档插件,你可以删除这个目录,或者你也可以在设置path
选项之后修改它的名称。 详情可参考文档指南/src/
- 如页面或自定义 React 组件一类的非文档文件。 严格来说,你不一定要把非文档类文件放在这里。不过把它们放在一个集中的目录,可以让代码检查或者处理更为简便。/src/pages
- 所有放在此目录中的 JSX/TSX/MDX 文件都会被转换成网站页面。 详情可参考页面指南
/static/
- 静态目录。 此处的所有内容都会被复制进build
文件夹/docusaurus.config.js
- 站点配置文件。 这等效于 Docusaurus 1 中的siteConfig.js
文件/package.json
- Docusaurus 网站是一个 React 应用。 你可以安装并使用任何 npm 包。/sidebars.js
- 由文档使用,用于指定侧边栏中的文档顺序
单仓模式
如果你打算用 Docusaurus 来给一个现有的项目搭建文档,单仓模式可能是一种解决方案。 单仓允许你在类似项目间共享依赖项。 例如,您的网站可以使用本地软件包来展示最新功能,而不是依赖已发布的版本。 然后,您的贡献者可以在实现功能的同时更新文档。 下面是单仓模式文件夹结构的一个例子:
my-monorepo
├── package-a # 另一个包,你的项目本身
│ ├── src
│ └── package.json # package-a 的依赖项
├── website # Docusaurus 根目录
│ ├── docs
│ ├── src
│ └── package.json # Docusaurus 的依赖项
├── package.json # 单仓的共享依赖项
这种情况下,你应该在 /my-monorepo
文件夹中运行 npx create-docusaurus
。
如果你在用 Netlify 或 Vercel 等托管平台,你需要把网站的 Base directory
修改到你的 Docusaurus 根目录的位置。 在上面这个例子里,就是./website
。 要了解更多关于怎么配置忽略命令的信息,可以阅读部署文档。
你可以在 Yarn 的文档中了解更多关于单仓的信息(Yarn 并不是建立单仓的唯一方法, 但这是常见的方案之一),或者参考 Docusaurus 和 Jest 等一些真实案例。
运行开发服务器
要实时预览你的编辑,你可以运行本地开发服务器。它会部署你的网站,并反映最新更改。
- npm
- Yarn
- pnpm
cd my-website
npm run start
cd my-website
yarn run start
cd my-website
pnpm run start
如果不进行额外配置,浏览器会默认打开 localhost:3000
恭喜! 你刚刚成功创建了你的首个 Docusaurus 网站! 四处逛逛,看看有什么功能吧。
构建
Docusaurus 是一款现代化的静态网页生成器。因此,我们需要将网站生成为静态内容,并上传到网络服务器,才能被其他人访问。 要构建站点,请使用以下命令:
- npm
- Yarn
- pnpm
npm run build
yarn build
pnpm run build
网站内容会被生成在 /build
目录中,随后可以被上传到 GitHub Pages、Vercel、Netlify 等静态网页托管服务。 请查看部署流程了解详情。
更新 Docusaurus
要更新你的 Docusaurus 版本,有很多方法。 一种保险的方法是把 package.json
中的版本号手动修改成指定版本。 请注意,所有以 @docusaurus/
开头的包都需要使用同一版本。
你正在浏览未发布版本的文档。如果你想使用任何未发布功能,你可以使用@canary
版本。
{
"dependencies": {
"@docusaurus/core": "3.6.0",
"@docusaurus/preset-classic": "3.6.0",
// ...
}
}
接下来,在包含 package.json
的项目文件夹里,运行你的包管理器的安装命令:
- npm
- Yarn
- pnpm
npm install
yarn install
pnpm install
npm install
may report several vulnerabilities and recommend running npm audit
to address them. Typically, these reported vulnerabilities, such as RegExp DOS vulnerabilities, are harmless and can be safely ignored. Also read this article, which reflects our thinking: npm audit: Broken by Design.
要检查更新是否成功,可以运行:
npx docusaurus --version
你应该能看到正确的版本输出。
如果你使用 Yarn,你也可以用如下命令:
yarn add @docusaurus/core @docusaurus/preset-classic
想要使用 Docusaurus 最新的未发布功能,可以安装 npm 上的 @canary
版本。
遇到了什么问题吗?
Ask for help on Stack Overflow, on our GitHub repository, our Discord server, or X.