主配置文件
Docusaurus 的主配置文件是 docusaurus.config.js ，它是一个标准的 JavaScript（或 TypeScript）导出对象，整个项目的运行和行为基本都由它控制。
从高维度来说，Docusaurus 配置可被分为这几类：
- 站点元数据
- 部署配置
- 主题、插件和预设配置
- 自定义配置
Docusaurus 配置文件介绍 讲的是一些规则，但没有完整的示例。
docusaurus.config.js
jsdocusaurus.config.js 示例
// @ts-check
// 注意：这是一个 Docusaurus 配置文件的示例
const config = {
title: "我的学习网站", // 网站标题，会显示在导航栏和浏览器标签上
tagline: "记录与分享", // 介绍
url: "https://example.com", // 站点域名
baseUrl: "/", // 部署时的基础路径。不懂就保持当前配置。
favicon: "img/favicon.ico", // 网站在浏览器标签上显示的图标
// GitHub 部署相关。
// 用不上可以注释掉。
organizationName: "my-org", // GitHub 用户名
projectName: "my-site", // GitHub 仓库名
// 国际化配置（仅使用中文）
i18n: {
defaultLocale: 'zh-CN',
locales: ['zh-CN'],
},
// 链接错误处理
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
// 启用未来特性（比如 faster）
future: {
v4: true, // 无所谓，遇到Bug就关闭，没有就打开。
experimental_faster: false, // 开启后可以加快编译速度2x左右，但截至目前最新的Docusaurus 3.8.1版本，仍有Bug，不建议开启。
},
// 与主题相关的预设
presets: [
[
// 经典主题（似乎只有这个主题）
"classic",
/** @type {import('@docusaurus/preset-classic').Options} */
({
// 文档相关的配置
docs: {
// 导入侧边栏生成规则
sidebarPath: require.resolve("./sidebars.js"),
},
// 博客相关的配置
blog: {
// 显示：预计阅读时间 xx 分钟
showReadingTime: true,
},
// 主题配置相关
theme: {
// 自定义主题CSS 用户可以在 `项目/src/css/custom.css` 中添加自己的CSS，完成自定义主题。
customCss: require.resolve("./src/css/custom.css"),
},
}),
],
],
// 主题配置
themeConfig: {
// 配置顶部导航栏 navbar
navbar: {
// 页面顶部显示的网站的名称
title: "我的学习网站",
// 网站的logo
logo: {
alt: "站点 Logo",
src: "img/logo.svg",
},
// 在此添加、修改、删除导航栏中的项
items: [
{ to: "/docs/intro", label: "文档", position: "left" },
{ to: "/blog", label: "博客", position: "left" },
{
href: "https://github.com/my-org/my-site",
label: "GitHub",
position: "right",
},
],
},
// 配置底部导航栏（一些链接）footer
footer: {
// 背景颜色 亮色/暗色
style: "dark",
// 添加、修改、删除链接。链接出现在页面底部
links: [
{
title: "文档",
items: [
{ label: "入门", to: "/docs/intro" },
],
},
{
title: "社区",
items: [
{ label: "GitHub", href: "https://github.com/my-org/my-site" },
],
},
],
// 版权声明
copyright: `Copyright © ${new Date().getFullYear()} My Org.`,
},
},
};
module.exports = config;
所有配置都写在 docusaurus.config.js 会非常长，难以阅读。所以官方把侧边栏相关配置拆分到 sedebar.js 。
你也可以根据需要拆分配置到不同的文件，当你逐渐熟悉 Docusaurus 你会想要加入一些新的功能和配置，你可以创建自己的 scripts 、 plugins 目录，并编写脚本或插件，最终需在 docusaurus.config.js 中导入它们。
sidebar.js
sidebars.js 精细控制侧边栏目录的生成。默认配置很简单， autogenerated 表示自动包含指定目录的侧边栏， . 代表 docs 目录。
js
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
docs: [
{
type: 'autogenerated',
dirName: '.', // 从 docs 根目录开始自动生成
},
],
};
export default sidebars;
随着文档数量和分类增加
bash
// 目录结构
docs
├── computer
│ ├── intro.md
│ ├── os.md
│ ├── ...数百个.md
│ └── networking.md
└── biology
├── intro.md
├── ...数百个.md
├── genetics.md
└── ecology.md
为 docs 目录下不同文件夹配置单独的侧边栏：
js
// sidebars.js
const sidebars = {
// 计算机类文档
computerSidebar: [{ type: "autogenerated", dirName: "computer" }],
// 生物类文档
biologySidebar: [{ type: "autogenerated", dirName: "biology" }],
};
module.exports = sidebars;
如何处理错误链接
| 值 | 含义说明 |
|---|---|
throw | 构建时遇到断链会直接抛出错误并终止构建 |
warn | 构建时输出警告，但不会中止构建 |
ignore | 忽略断链（不建议使用，可能造成发布后 404） |
js
// 配置 build 过程中遇到无效链接时的行为。throw:抛出错误并停止。
onBrokenLinks: "throw",
// 配置 build 过程中 Markdown 文件中遇到无效链接时的行为。warn：输出警告信息，但不会停止。
onBrokenMarkdownLinks: "warn",
如何关闭 blog
js
const config = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
path: 'docs', // 文档目录
routeBasePath: '/', // 文档作为网站首页
sidebarPath: require.resolve('./sidebars.js'), // 侧边栏配置
// 没有仓库，不使用 editUrl
},
blog: false, // 禁用博客
pages: true, // 启用自定义页面（src/pages）
},
],
],
}
如何设置文章解析器
默认情况，Docusaurus 使用 MDX 解析器解析所有文章，用户可以设置解析器：
jsdocusaurus.config.js
markdown: {
// 可以设置为 md | mdx | detect
format: 'detect',
},
| 选项 | 文档后缀 .md | 文档后缀 .mdx |
|---|---|---|
| mdx | MDX | MDX |
| md | Markdown | Markdown |
| detect（根据后缀） | Markdown | MDX |
tip
如果你打算深入使用 Docusaurus 推荐使用默认解析。