facebook / facebook/docusaurus
Autogenerated sidebar items: allow more control on output
- Lenguaje dominante
- TypeScript
- Estrellas
- 66.2k
- Forks
- 10k
- Merge medio
- 1 d 3 h
- PR fusionados (30 d)
- 52
Descripción
## 🚀 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
Guía de contribución
Evaluación
Este issue todavía no se ha evaluado.