自動產出

Docusaurus 可以自動建立側邊欄，依循您的檔案系統結構：每個資料夾都會建立一個側邊欄類別，每個檔案則建立一個文件連結。

type SidebarItemAutogenerated = {
  type: 'autogenerated';
  dirName: string; // Source folder to generate the sidebar slice from (relative to docs)
};

Docusaurus 可以根據您的文件資料夾來產生完整的側邊欄

sidebars.js

export default {
  myAutogeneratedSidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // '.' means the current docs folder
    },
  ],
};

Docusaurus 會將一個 autogenerated 項目轉換成一個側邊欄區塊（在 類別簡寫 中也有討論）：一個類型為 doc 或 category 的項目列表，因此您可以在同一個側邊欄層級中，把多個目錄中的多個 autogenerated 項目組合在一起，並加上一般側邊欄項目。

實際範例

考量下列檔案結構

docs
├── api
│   ├── product1-api
│   │   └── api.md
│   └── product2-api
│       ├── basic-api.md
│       └── pro-api.md
├── intro.md
└── tutorials
    ├── advanced
    │   ├── advanced1.md
    │   ├── advanced2.md
    │   └── read-more
    │       ├── resource1.md
    │       └── resource2.md
    ├── easy
    │   ├── easy1.md
    │   └── easy2.md
    ├── tutorial-end.md
    ├── tutorial-intro.md
    └── tutorial-medium.md

假設每個文件的 ID 就是它的檔案名稱。如果您定義一個自動產生的側邊欄，如下所示

sidebars.js

export default {
  mySidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorials',
      items: [
        'tutorial-intro',
        {
          type: 'autogenerated',
          dirName: 'tutorials/easy', // Generate sidebar slice from docs/tutorials/easy
        },
        'tutorial-medium',
        {
          type: 'autogenerated',
          dirName: 'tutorials/advanced', // Generate sidebar slice from docs/tutorials/advanced
        },
        'tutorial-end',
      ],
    },
    {
      type: 'autogenerated',
      dirName: 'api', // Generate sidebar slice from docs/api
    },
    {
      type: 'category',
      label: 'Community',
      items: ['team', 'chat'],
    },
  ],
};

將會解析成

sidebars.js

export default {
  mySidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorials',
      items: [
        'tutorial-intro',
        // Two files in docs/tutorials/easy
        'easy1',
        'easy2',
        'tutorial-medium',
        // Two files and a folder in docs/tutorials/advanced
        'advanced1',
        'advanced2',
        {
          type: 'category',
          label: 'read-more',
          items: ['resource1', 'resource2'],
        },
        'tutorial-end',
      ],
    },
    // Two folders in docs/api
    {
      type: 'category',
      label: 'product1-api',
      items: ['api'],
    },
    {
      type: 'category',
      label: 'product2-api',
      items: ['basic-api', 'pro-api'],
    },
    {
      type: 'category',
      label: 'Community',
      items: ['team', 'chat'],
    },
  ],
};

請注意，自動產生的來源目錄本身並不會變成類別：只有它們包含的項目會變成類別。這就是我們所謂的「側邊欄區塊」。

類別索引慣例

Docusaurus 可以將一個類別自動連結至其索引文件。

類別索引文件是一個遵循下列檔案名稱慣例的文件

• 命名為 index（大小寫不分）：docs/Guides/index.md
• 命名為 README（大小寫不分）：docs/Guides/README.mdx
• 與父資料夾同名：docs/Guides/Guides.md

這等同於使用具有文件連結的類別

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {type: 'doc', id: 'Guides/index'},
      items: [],
    },
  ],
};

秘訣

將您的介紹文件命名為 README.md 會讓它在使用 GitHub 介面瀏覽資料夾時顯示出來，而使用 index.md 會讓行為更符合 HTML 檔案的提供方式。

秘訣

如果一個資料夾只有一個索引頁面，它會變成連結而不是類別。這對資源配置很有用

some-doc
├── index.md
├── img1.png
└── img2.png

自訂類別索引匹配

可以選擇不使用任何類別索引慣例，或者定義更多慣例。您可以透過sidebarItemsGenerator 回呼注入您自己的 isCategoryIndex 辨識器。例如，您也可以選擇 intro 為另一個有資格自動成為類別索引的檔名。

docusaurus.config.js

export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          ...args,
          isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below
          defaultSidebarItemsGenerator,
        }) {
          return defaultSidebarItemsGenerator({
            ...args,
            isCategoryIndex(doc) {
              return (
                // Also pick intro.md in addition to the default ones
                doc.fileName.toLowerCase() === 'intro' ||
                defaultCategoryIndexMatcher(doc)
              );
            },
          });
        },
      },
    ],
  ],
};

或者選擇不使用任何類別索引慣例。

docusaurus.config.js

export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          ...args,
          isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below
          defaultSidebarItemsGenerator,
        }) {
          return defaultSidebarItemsGenerator({
            ...args,
            isCategoryIndex() {
              // No doc will be automatically picked as category index
              return false;
            },
          });
        },
      },
    ],
  ],
};

isCategoryIndex 辨識器將提供三欄位

• fileName，檔名，不包含副檔名且保留大小寫
• directories，目錄名稱的清單從最底層到最高層，相對於文件根目錄
• extension，檔名的副檔名，前面有句點。

例如，對於位於 guides/sidebar/autogenerated.md 的一個文件檔，辨識器接收到的屬性為

const props = {
  fileName: 'autogenerated',
  directories: ['sidebar', 'guides'],
  extension: '.md',
};

預設實作為

function isCategoryIndex({fileName, directories}) {
  const eligibleDocIndexNames = [
    'index',
    'readme',
    directories[0].toLowerCase(),
  ];
  return eligibleDocIndexNames.includes(fileName.toLowerCase());
}

自動產生的側邊欄資訊

對於手寫側邊欄定義，您會透過 `sidebars.js` 為側邊欄項目提供元資料；對於自動產生的部分，Docusaurus 會從項目的個別檔案讀取這些元資料。此外，您可能想要調整每個項目的相對位置，因為預設上，側邊欄區段中的項目會以字母順序產生（使用檔案與資料夾名稱）。

文件元資料

label、className 和 customProps 屬性分別於 front matter 中宣告為 sidebar_label、sidebar_class_name 和 sidebar_custom_props。位置也能以相同的方式，透過 sidebar_position front matter 指定。

docs/tutorials/tutorial-easy.md

---
sidebar_position: 2
sidebar_label: Easy
sidebar_class_name: green
---

# Easy Tutorial

This is the easy tutorial!

類別元資料

在個別資料夾中新增 _category_.json 或 _category_.yml 檔案。您可以指定任何類別元資料以及 position 元資料。如果有的話，label、className、position 和 customProps 會預設為類別連結文件的各個值。

JSON

docs/tutorials/_category_.json

{
  "position": 2.5,
  "label": "Tutorial",
  "collapsible": true,
  "collapsed": false,
  "className": "red",
  "link": {
    "type": "generated-index",
    "title": "Tutorial overview"
  },
  "customProps": {
    "description": "This description can be used in the swizzled DocCard"
  }
}

YAML

docs/tutorials/_category_.yml

position: 2.5 # float position is supported
label: 'Tutorial'
collapsible: true # make the category collapsible
collapsed: false # keep the category open by default
className: red
link:
  type: generated-index
  title: Tutorial overview
customProps:
  description: This description can be used in the swizzled DocCard

資訊

如果明確指定 link，Docusaurus 就不會套用任何 預設慣例。

文件連結可以以相對路徑指定，例如，如果類別是使用 guides 目錄產生的，"link": {"type": "doc", "id": "intro"} 將會解析為 ID guides/intro，如果前者 ID 的文件不存在，才會替換成 intro。

您也可以使用 link: null 來選擇停用預設慣例，不產生任何類別索引頁面。

資訊

位置元資料只會用於側邊欄區段中：Docusaurus 不會重新排列側邊欄中的其他項目。

使用數字前綴

對自動產生的側邊欄進行排序的簡單方法，就是在文件和資料夾前加上數字前綴，這也會讓它們在根據檔名排序後以相同的順序顯示在檔案系統中。

docs
├── 01-Intro.md
├── 02-Tutorial Easy
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   └── 03-End.md
├── 03-Tutorial Advanced
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   ├── 03-Third Part.md
│   └── 04-End.md
└── 04-End.md

為了讓採納更輕鬆，Docusaurus 支援多重數字前綴模式。

在預設的情況下，Docusaurus 會從文件識別碼、標題、標籤和 URL 路徑移除數字前綴。

警告

建議使用 其他元資料.

更新數字前綴可能會很煩人，因為它可能需要更新多個現有的 Markdown 連結

文件/02-簡易教學/01-第一部分.md

- Check the [Tutorial End](../04-End.mdx);
+ Check the [Tutorial End](../05-End.mdx);

自訂側邊欄項目產生器

您可以在文件外掛程式 (或預設值) 設定檔中提供自訂的 sidebarItemsGenerator 函式

docusaurus.config.js

export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          defaultSidebarItemsGenerator,
          numberPrefixParser,
          item,
          version,
          docs,
          categoriesMetadata,
          isCategoryIndex,
        }) {
          // Example: return an hardcoded list of static sidebar items
          return [
            {type: 'doc', id: 'doc1'},
            {type: 'doc', id: 'doc2'},
          ];
        },
      },
    ],
  ],
};

秘訣

重複使用並增強預設產生器，而不是從頭開始撰寫產生器：我們提供的預設產生器 長度為 250 行。

根據您的使用案例新增、更新、篩選、重新排列側邊欄項目

docusaurus.config.js

// Reverse the sidebar items ordering (including nested category items)
function reverseSidebarItems(items) {
  // Reverse items in categories
  const result = items.map((item) => {
    if (item.type === 'category') {
      return {...item, items: reverseSidebarItems(item.items)};
    }
    return item;
  });
  // Reverse items at current level
  result.reverse();
  return result;
}

export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
          const sidebarItems = await defaultSidebarItemsGenerator(args);
          return reverseSidebarItems(sidebarItems);
        },
      },
    ],
  ],
};