facebook / facebook/docusaurus

Autogenerated sidebar items: allow more control on output

Đang mở
#5,689 32 bình luận 21 reaction 0 người được giao Xem trên GitHub
feature status: needs more information
Ngôn ngữ chính
TypeScript
Star
66.2k
Fork
10k
Merge trung bình
1 ngày 3 giờ
Pull request đã merge (30 ngày)
52

Mô tả

## 🚀 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

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.