facebook / facebook/docusaurus

Autogenerated sidebar items: allow more control on output

未关闭
#5,689 32 条评论 21 个 reaction 已指派 0 人 在 GitHub 查看
feature status: needs more information
主要语言
TypeScript
星标
66.2k
派生
10k
平均合并
1 天 3 小时
30 天内合并 PR
52

描述

## 🚀 Feature

Several things:

- Add `exclude` option in category metadata to filter out docs;
- Add `additionalItems` option to include more items in autogenerated categories, including `link`, `ref`, etc.;
- Exclude entire subdirectories when declaring autogenerated sidebar items.

### Have you read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues)?

Yes

### Has this been requested on [Canny](https://docusaurus.io/feature-requests)?

No, but there are inline comments asking if they should be allowed, and the answer is yes: I've been asked about this feature.

## Motivation

Sometimes we want a fully autogenerated sidebar, but occasionally want to add a few external links in categories. Sometimes we have a legacy directory structure and we only want to generate the sidebar from part of that directory.

## API Design

In `_category_.json`, add the following options:

```diff
type CategoryMetadatasFile = {
label?: string;
position?: number;
collapsed?: boolean;
collapsible?: boolean;
className?: string;
+ additionalItems?: WithPosition[];
+ exclude?: {
+ paths: string[];
+ docIDs?: string[];
+ };
};
```

`paths` accepts folder paths (I don't know if file paths would work well; from my experience with the autogenerator code, seems it's not easy since the doc metadata only includes `sourceDir`?), while `docIDs` accepts... doc IDs. It's assumed that the members in these two arrays are otherwise included in the category; if they are never included (non-existent IDs/paths not in the autogen dir...), maybe throw an error, or maybe do nothing.

`additionalItems` accepts `doc`, `ref`, `link`, and even `category`, but not `autogenerated` (at least I think it doesn't make much sense, and opens up holes to infinite recursion). Because `doc` items already come with their own `sidebarPosition`, they will be sorted well with the rest of the items. However, all items can have an additional `sidebarPosition` attribute (hence `WithPosition`) to override this behavior.

The `autogenerated` sidebar item will also accept the `exclude` and `additionalItems` properties, because the metadata file in the autogen dir root is not read.

## Have you tried building it?

No

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。