配置

Docusaurus 之所以如此受欢迎，是因为其配置简单，仅需简单的配置就可以实现强大的功能，并且支持丰富的自定义能力。由于官方默认文档 Style 配置，在此基础上发现 Docusaurus 也很适合作为书本 Style，当然你也可以自定义开发，我这里仅仅是在使用官方提供的常用配置功能来演示

本篇文章是两种风格的一些通用配置，当然官方还有很多的配置，这里只列举了常用的配置，更多配置可以参考官方文档 docusaurus.config.js

侧边栏

侧边栏有两种方式，一种是手动配置，另一种可根据指定路径自动生成，无论使用那种方式都需要两步：

1. 定义 sidebar.ts

在配置侧边栏时有多种类型

Doc: 文档页面的链接，并和侧边栏绑定
Link：内部或外部页面链接
Category：创建侧边栏项下拉菜单
Autogenerated：自动生成侧边栏切片
HTML：在这个位置渲染纯 HTML
*Ref：链接到文档页面，但项目不会参与生成导航

sidebars.ts
export default {
  mySidebar: [
    // 常规语法：
    {
      type: 'doc',
      id: 'doc1', // 文档 ID
      label: 'Getting started', // 侧边栏标签
    },
    // 简写语法：
    'doc2', // 文档 ID
    ],
};

sidebars.ts
export default {
  myLinksSidebar: [
    // 外部链接
    {
      type: 'link',
      label: 'Facebook', // 链接标签
      href: 'https://facebook.com', // 外部 URL
    },

    // 内部链接
    {
      type: 'link',
      label: 'Home', // 链接标签
      href: '/', // 内部路径
    },
  ],
};

sidebars.ts
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {
        // 快速生成介绍文档
        type: 'generated-index',
        // 侧边栏标签
        title: 'Docusaurus 教程',
        // Guides 目录介绍
        description: '学习最重要的 Docusaurus 概念!',
        // 自定义生成页面的路径
        slug: '/category/docusaurus-guides',
        keywords: ['guides'],
        image: '/img/docusaurus.png',
      },
      // 侧边栏 Guides 目录列表
      items: [
        'creating-pages',
        {
          type: 'category',
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

在 Category 或 Autogenerated 类型下，侧边栏的索引页配置可以使用 _category_.yml 或 _category_.json 文件来配置

_category_.yml
_category_.json

yml 配置，推荐使用，link 为空时，即不会生成索引页

position: 2.5 # 支持浮点数序号
label: '教程' # 侧边栏标签
collapsible: true # 让类别可折叠
collapsed: false # 让类别默认开启
className: red # 标签类名定义
link:
  type: generated-index
  title: 教程总览
customProps:
  description: 这个描述可以用在 swizzle 的 DocCard 里

json 配置，description 索引页文本内容

{
  "position": 2.5,
  "label": "教程",
  "collapsible": true,
  "collapsed": false,
  "className": "red",
  "link": {
    "type": "generated-index",
    "title": "教程总览"
  },
  "customProps": {
    "description": "这个描述可以用在 swizzle 的 DocCard 里"
  }
}

sidebars.ts
export default {
  myHtmlSidebar: [
    {
      type: 'html', // 要渲染的 HTML
      value: '<img src="sponsor.png" alt="Sponsor" />',
      defaultStyle: true,  // 使用默认的菜单项目样式
    },
  ],
};

sidebars.ts
export default {
  myAutogeneratedSidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // '.' 即当前 docs 文件夹
    },
  ],
};

sidebars.ts
export default {
  tutorialSidebar: {
    'Category A': [
      'doc1',
      'doc2',
      {type: 'ref', id: 'commonDoc'},
      'doc5',
    ],
  },
  apiSidebar: ['doc3', 'doc4', 'commonDoc'],
};

2. docusaurus.config.ts

直接将此对象传入 @docusaurus/plugin-docs 或通过 @docusaurus/preset-classic 传入

docusaurus.config.ts
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
        },
      },
    ],
  ],
};

主题颜色

可通过 Infima 进行生成主题色

src/css/custom.css
/* 默认颜色. */
:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
  --ifm-code-font-size: 95%;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
}

/* dark 模式颜色. */
[data-theme='dark'] {
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: #21af90;
  --ifm-color-primary-darker: #1fa588;
  --ifm-color-primary-darkest: #1a8870;
  --ifm-color-primary-light: #29d5b0;
  --ifm-color-primary-lighter: #32d8b4;
  --ifm-color-primary-lightest: #4fddbf;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
}

代码块

信息

Docusaurus: 默认支持的高亮语言
Prism: 可配置支持语言

以下展示了 Docusaurus 默认不支持的语言配置

docusaurus.config.ts
const config: Config = {
  themeConfig: {
    prism: {
      additionalLanguages: [
        'java',
        'bash',
        'json'
      ],
    }
  }
}

在 3.4.0 版本，由于 jiti 版本问题，添加 Docusaurus 不支持的语言，并未生效，可对 jiti 的版本强制指定
package.json
"resolutions": {
  "jiti": "1.21.0"},

📄️ 文档 Style

这里所说的文档 Style，指的具有 Home 页，这种风格很适合作为综合技术类的网站，比如一些案例展示

📄️ 书本 Style

这里所说的书本 Style，指的不具有 Home 页，这种风格很适合作为纯技术内容输出的网站，是 hugo-book 的平替

侧边栏​

1. 定义 sidebar.ts​

2. docusaurus.config.ts​

主题颜色​

代码块​

📄️ 文档 Style

📄️ 书本 Style

侧边栏

1. 定义 sidebar.ts

2. docusaurus.config.ts

主题颜色

代码块