开启掘金成长之旅！这是我参与「掘金日新计划 · 12 月更文挑战」的第48天，点击查看活动详情

docusaurus.js

独立页面​

1. 在 src/pages 下的每一个 js 或者 md 文件都会被认定为一个页面。每个文件夹 的index.js会被认为成这个文件夹为名称的页面
2. 在src/pages 下所有以 _ 开头的文件都会被忽略，不会成为页面。

文档功能介绍​

文档 id​

每个文档都有自己的 id ，id 的默认值为文档路径名称

• /docs/aa.md id 自动生成为 aa
• /docs/start/one.md id 自动生成为 start/one

用户可以在 md 文件内部可以自定义 id 。

---
id: part1
---
Lorem ipsum

文档 router​

现有一个文档，其路由的访问路径为：\docs\guide\hello，但我们想通过的别的路由访 问该文档，比如/aa/bb

website # Root directory of your site
└── docs
    └── guide
        └── hello.md

通过在hello.md文件内部修改 slug 这个值为：/aa/bb ，我就能通 过/docs/aa/bb这个路由访问该页面。

---
slug: /aa/bb    # / 代表了 /docs
---

Lorem ipsum

文档模式​

一进入站点就是文档的页面的路由：

1. 配 置
2. 配置作为首页的文 档
3. 必须删除 index.js，否则这两个路由会映射到同一个页面。

侧边栏​

若想在文档上使用侧边栏，则需要配置：

1. 定义一个侧边栏配置文件。

2. 在docusaurus.config.js 中进行配置。

   module.exports = {
     presets: [
       [
         '@docusaurus/preset-classic', // 或者'classic'
         {
           docs: {
             sidebarPath: require.resolve('./sidebars.js'), // 引入侧边栏配置文件
           },
         },
       ],
     ],
   };
   

默认生成侧边栏​

如果sidebars.js未配置侧边栏，则默认自动生成侧边栏。

// sidebars.js
// 默认的配置
module.exports = {
  mySidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // generate sidebar from the docs folder (or versioned_docs/<version>)
    },
  ],
};

自定义侧边栏​

侧边栏有 n 种类型：

1️⃣ doc：文档类型，链接到文档页面

type SidebarItemDoc =
  // 正常的语法
  | {
      type: 'doc',
      id: string,
      label: string, // 侧边栏的显示文本
      className?: string, // 侧边栏项的class类名
      customProps?: Record<string, unknown>, // 自定义属性
    }

  // 简单的语法
  | string; // docId 文档id

// sidebars.js
module.exports = {
  mySidebar: [
    {
      type: 'doc',
      id: 'doc1',
      label: '首页',
      className: 'sideItem',
      customProps: {
        name: 'xyb',
      },
    },
    'doc1', // 直接写文档id
  ],
};

2️⃣ category：目录类型，在侧边栏生成下拉列表，形成层次结构

type SidebarItemCategory = {
  type: 'category';
  label: string; // 侧边栏的显示文本
  items: SidebarItem[]; // 子项
  className?: string;

  // Category options:
  collapsible: boolean; // 设置是否可折叠(关闭折叠功能) 【可以在docusaurus.config.js全局设置】
  collapsed: boolean; // 设置初始侧边栏是否展开 【可以在docusaurus.config.js全局设置】
  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};

自定义下拉侧边栏：

module.exports = {
  mySidebar: [
    'index',
    {
      type: 'category',
      label: '指导',
      items: [
        'intro',
        {
          type: 'category',
          label: '二层指导',
          items: ['tutorial-basics/congratulations'],
        },
      ],
    },
  ],
};

若不需要自定义，则可以直接简写：

module.exports = {
  mySidebar: [
    'index',
    {
      我是简写语法: ['Getting Started/doc1'],
    },
  ],
};

下拉列表框链接，让下拉列表框也能链接文档，需要添加 link 属性

module.exports = {
  mySidebar: [
    'index',
    {
      type: 'category',
      label: '指导',
      link: {
        type: 'doc',
        id: 'Getting Started/doc1'
      },
      items: [ ... ]
    }
  ],
};

• link：外部链接类型

侧边栏配置​

可隐藏侧边栏​

能够隐藏侧边栏

// docusaurus.config.js
module.exports = {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: true,
      },
    },
  },
};

自动则折叠侧边栏​

打开一个侧边栏，其余侧边栏隐藏，减少空间冗余

// docusaurus.config.js
module.exports = {
  themeConfig: {
    docs: {
      sidebar: {
        autoCollapseCategories: true,
      },
    },
  },
};

面包屑导航​

关闭面包屑导航

// docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          breadcrumbs: false,
        },
      },
    ],
  ],
};