facebook / facebook/docusaurus

Autogenerated sidebar items: allow more control on output

オープン
#5,689 コメント 32 件 リアクション 21 件 担当者 0 名 GitHub で見る
feature status: needs more information
主要言語
TypeScript
スター
66.2k
フォーク
10k
平均マージ
1日 3時間
マージ済み PR(30日)
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 を短くまとめたダイジェスト。