Docusaurus：基于 React 的文档站点生成器
id: getting-started title: 快速开始 sidebar_position: 1
快速开始
欢迎使用我们的产品！本节将引导你在 5 分钟内 完成核心功能的配置。
前置要求
- 确保已安装 Node.js 18+
- 具备基本的命令行操作能力
安装
在终端运行：
npm install my-library
- 文件头部的 `---` 包裹的部分是 **Front Matter**，用于定义文档的 ID、标题和侧边栏位置。
- `sidebar_position` 是一个数字，表示该文档在侧边栏中的排列顺序。
- 内容主体遵循标准 Markdown 语法，Docusaurus 会自动将其渲染为 HTML。
### 2. 配置侧边栏
打开 `sidebars.js`，默认配置如下：
```javascript
// @ts-check
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
};
module.exports = sidebars;
autogenerated 类型会根据 docs/ 目录下的文件结构和 Front Matter 自动生成侧边栏。你不需要手动列出每一个文档，非常方便。
3. 预览结果
刷新浏览器，侧边栏中就会出现“快速开始”条目，点开后即可看到你刚刚编写的内容。Docusaurus 会基于 Front Matter 中的标题自动变为可折叠的导航。
文档的高级功能
跨文档链接
你可以通过相对路径或文档 ID 来链接其他文档。例如，从 getting-started.md 链接到高级配置文档 advanced.md（假设其 id 为 advanced）：
请参考 [高级配置](./advanced.md) 或直接使用 ID 链接 [高级配置](advanced)。
推荐使用基于文件路径的 .md 引用，Docusaurus 会在构建时检查链接的有效性。
图片与静态资源
将图片放入 static/img/ 目录下，然后在 Markdown 中使用路径引用：
使用 / 开头的绝对路径，它会指向 static/ 文件夹。
使用代码块和行高亮
Docusaurus 使用 Prism 作为语法高亮引擎。你可以指定语言并高亮特定行：
```jsx {3,5-7}
import React from 'react';
function Hello() {
return (
<div>
<h1>你好，世界</h1>
</div>
);
}
```
花括号内的数字表示高亮的行号。
提示框（Admonitions）
Docusaurus 内置了多种提示框，用于突出显示重要信息：
:::note
这是一条普通注释。
:::
:::tip 小贴士
这里有一个实用技巧。
:::
:::warning
此操作不可逆，请谨慎操作。
:::
多版本文档
当你需要维护不同版本的文档时，只需运行以下命令：
npm run docusaurus docs:version 1.0
这会将当前 docs 下的所有内容复制一份到 versioned_docs/version-1.0/，并生成一个版本化的侧边栏。之后你可以继续在 docs/ 下撰写“下一版本”的文档。用户可以通过顶部的版本下拉菜单切换不同版本文档。
自定义页面和样式
Docusaurus 基于 React，你可以轻松添加自定义页面或覆盖主题样式。
添加自定义页面
在 src/pages/ 目录下新建一个 React 组件文件，如 hello.js：
import React from 'react';
import Layout from '@theme/Layout';
export default function Hello() {
return (
<Layout title="Hello" description="自定义页面">
<div style={{ textAlign: 'center', marginTop: '50px' }}>
<h1>你好，Docusaurus！</h1>
<p>这是一个完全自定义的页面。</p>
</div>
</Layout>
);
}
访问 http://localhost:3000/hello 就能看到这个页面。Docusaurus 自动将文件路径映射为路由。
覆盖主题样式
你可以通过“swizzling”来安全地覆盖主题组件，也可以直接在 src/css/custom.css 中修改 CSS 变量。例如，更改主色调：
:root {
--ifm-color-primary: #e23e57;
--ifm-color-primary-dark: #d92a45;
/* 其他颜色... */
}
开发服务器会自动刷新，使你的站点更具个性。
搜索集成
一个好的文档站离不开搜索功能。Docusaurus 内置了 Algolia DocSearch 支持，你也可以开启本地搜索。
启用本地搜索
安装插件：
npm install --save @easyops-cn/docusaurus-search-local
然后在 docusaurus.config.js 中配置：
themes: [
[
require.resolve('@easyops-cn/docusaurus-search-local'),
{
hashed: true,
language: ['zh', 'en'],
},
],
],
重启开发服务器后，导航栏会出现一个搜索框，可以搜索所有文档标题和内容。
构建与部署
当你准备好让网站上线时，需要构建为静态文件。
1. 生成静态文件
运行：
npm run build
构建产物会输出到 build/ 文件夹。这些文件就是可以直接部署到任何静态主机上的全静态站点。
2. 部署到 GitHub Pages
Docusaurus 提供了便捷的部署命令。首先在 docusaurus.config.js 中设置 url 和 baseUrl，然后运行：
GIT_USER=<你的GitHub用户名> npm run deploy