facebook / facebook/docusaurus

RFC: Doc sidebar version dropdown

Aperta
#5,706 16 commenti 11 reazioni 0 assegnatari Vedi su GitHub
feature
Lingua principale
TypeScript
Stelle
66.2k
Fork
10k
Merge medio
1g 3h
PR unite (30g)
52

Descrizione

## 🚀 Feature

The navbar can get a bit crowded over time and it's a common doc pattern to use a sidebar version dropdown

The APISIX website already built this:

https://apisix.apache.org/docs/apisix/architecture-design/apisix

![image](https://user-images.githubusercontent.com/749374/137367886-1ebc0d18-9751-4b80-9926-906e89e882ca.png)

![image](https://user-images.githubusercontent.com/749374/137368024-5ce7e941-8cb8-404c-a8c4-1cb120a45f8d.png)

We could add some extra sidebar config to handle a version dropdown.

I don't have a strong opinion on the public API yet. Maybe it could be a theme config like `themeConfig.docSidebarVersionDropdown: true` ?

To me it does not make sense to:
- nest a version dropdown inside a sidebar category, so it can't be a sidebar item directly
- display 2+ versions dropdowns inside the same sidebar

But it could make sense to:
- display the dropdown at the bottom (sticky?) or the top (sticky?)
- have different config per-sidebar?

The current `sidebars.js` file is hard to modify to add some sidebar top-level sidebarr configs like booleans: we'd have to ensure backward compatibility but this is a possibility:

```js
const sidebars = {
mySidebar: {
versionDropdown: "top-sticky",
items: [...]
}
}
```

We could also add a type and allow it only as top-level item (simpler for retrocompatibility)?

```js
const sidebars = {
mySidebar: [{type: "versionDropdown"},...]
}
```

Note we want to enable custom navbar items and custom blog sidebar items, so maybe we also need to think about custom doc sidebar items too? I don't really have a use-case for this yet.

Just wanted to open the discussion around this feature's design.

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.