facebook / facebook/docusaurus

Autogenerated sidebar items: allow more control on output

Abierto
#5,689 32 comentarios 21 reacciones 0 asignados Ver en GitHub
feature status: needs more information
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

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.