facebook / facebook/docusaurus

RFC: Doc sidebar version dropdown

Open
#5,706 16 comments 11 reactions 0 assignees View on GitHub
feature
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.