Docusaurus 速查表

路由构建

导航栏排序

官方文档提供的使用文章元数据定义排序方式我觉得不够优雅：

不支持负数，即无法倒序。
只给某个文档指定一个很大的序号，依旧不能让它排列在队尾。

以上问题就导致每个文档都要添加序号，十分繁琐。

为此，在默认路由生成器的基础上，我自定义了一个路由生成函数，将类别元信息中 reversed = true 的子路由倒序排列。

为此，需要在需要倒序的文件夹中添加：

_category_.yml
customProps:
  reversed: true

但这个配置暂不支持一级路由，因为每个导航栏项目对应一个路由表，每个路由表会触发一次自定义的路由生成函数 sidebarItemsGenerator，即只有二级路由可以判断它是否是分类路由，从而读取自定义的类别元数据。

其实也有解决方案，就是完全重写路由生成函数，但我觉得没必要（主要是懒），因为一级路由肯定不会太多，手动给每个文档加个 sidebar_position 也能接受。

最后，如果实在是有某个文档需要放到最后，那也只好按字母顺序改一下文件名，同时在元数据里把它的 id 改成有意义的名字。

隐藏文档

在具体的文档中添加元数据：

draft: true

这表示这是一篇未完成的草稿，只在开发模式可见。

文档组件

文档卡片列表

在正文中生成当前页面层级下的所有页面卡片。

import DocCardList from '@theme/DocCardList';

<DocCardList />

警告

如果当前页面不在具体的分类中，构建时会报错。

折叠块

生成默认折叠状态的区块，其中summary是默认显示的内容：

<details>
  <summary>Toggle me!</summary>
  <div>
    <div>This is the detailed content</div>
    <br/>
    <details>
      <summary>
        Nested toggle! Some surprise inside...
      </summary>
      <div>😲😲😲😲😲</div>
    </details>
  </div>
</details>

效果 🪄

快点我!

这是详情内容。

再点一下! 有惊喜...

😲有个屁的惊喜...

选项卡

生成选项卡，通过分组 id 可以同步在其他选项卡点选的内容：

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId="operating-systems">
<TabItem value="win" label="Windows">Use Ctrl + C to copy.</TabItem>
<TabItem value="mac" label="macOS">Use Command + C to copy.</TabItem>
</Tabs>

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">Use Ctrl + V to paste.</TabItem>
  <TabItem value="mac" label="macOS">Use Command + V to paste.</TabItem>
</Tabs>

效果 🪄

Windows
macOS

Use Ctrl + C to copy.

Windows
macOS

Use Ctrl + V to paste.

代码块

添加标题

在说明文件名时很有用：

```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
  return <h1>Hello, {props.name}</h1>
}
```

效果 🪄

/src/components/HelloCodeTitle.js
function HelloCodeTitle(props) {
  return <h1>Hello, {props.name}</h1>
}

高亮代码行

```js
function HighlightSomeText(highlight) {
  if (highlight) {
    // highlight-next-line
    return '这行被高亮了！'
  }

  return '这里不会'
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return '这块被高亮了！'
  }
  // highlight-end

  return '这里不会'
}
```

效果 🪄

function HighlightSomeText(highlight) {
  if (highlight) {
    return '这行被高亮了！'
  }

  return '这里不会'
}

function HighlightMoreText(highlight) {
  if (highlight) {
    return '这块被高亮了！'
  }

  return '这里不会'
}

提示信息

五种不同风格的提示块：

:::note

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::tip 自定义标题

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::info

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::caution

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::danger

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

效果 🪄

备注