Ability to link navbar to a given sidebar

[slorber]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

Sometimes we just want to link to the first doc of a given sidebar, without having to specify a given doc ID.

This can be useful to implement tabs navigation, like on our site, RN, Jest...

          {
            type: 'doc',
            docId: 'introduction',
            label: 'Docs',
          },
          {
            type: 'doc',
            docId: 'cli',
            label: 'API',
          },

This could become more natural with:

          {
            type: 'docSidebar',
            id: 'docs',
            label: 'Docs',
          },
          {
            type: 'doc',
            id: 'api',
            label: 'API',
          },

Another use-case mentioned is to use the docs plugin for a podcast: https://thediffpodcast.com/docs/episode-10

This is not convenient because on each new episode it requires editing the config navbar items to link to that latest episode.

---

This shouldn't be too hard to implement so if any external contributor is interested, please let me know ;)

Self-service

• I'd be willing to do some initial work on this proposal myself.

[lmpham1]

I'd like to give this issue a try!

[slorber]

This may be more complicated than I thought.

The theme layout does not have access to all docs-related data (on purpose), but it can only read docs global data (like other docs-related navbar items).

I don't think there's enough data in this global data structure to be able to find out what the link should be.

Also, if a sidebar starts with a category, and that category has a generated-index (example: https://docusaurus.io/docs/category/getting-started), we should probably link to that index instead of the first doc.

Cf the podcast site above. If the "Episodes" category was a generated-index (it is not atm), the Episodes navbar link should probably link to this page instead of linking to the latest episode-10.

The new global data structure should probably look like this:

type GlobalSidebarLink = { label: string; path: string };

type GlobalSidebar = {
  link?: GlobalSidebarLink;
  // ... we may add other things here later
};

// already existing type
export type GlobalVersion = {
  // ...
  sidebars: Record<string, GlobalSidebar>;
};

Also, can we infer the navbar label from the link label so that the navbar label is optional? 🤷‍♂️ not sure if it's very useful but maybe in some cases?

[lmpham1]

The new global data structure should probably look like this:

@slorber ah so I assume after that we need to add a toGlobalSidebar function to convert the sidebar object in a LoadedVersion object into a GlobalSidebar object, and stick that object into the GlobalVersion object. Then in the Navbar Item module in theme, we can fetch the GlobalVersion -> get GlobalSidebar from it, which contains the link to the first doc, which we can use to link it to that navbar item.

Is this the approach you have in mind?

[Josh-Cena]

@lmpham1 Sounds about right. You can mimic how the toGlobalDoc function is implemented, and register the sidebars as global data. It would be a mapping from sidebar IDs to the first doc's URL.

[slorber]

Yes 👍

It would be a mapping from sidebar IDs to the first doc's URL.

For future proofness, I'd rather have an object with a link attribute, also the label

type GlobalSidebarLink = { label: string; path: string };

type GlobalSidebar = {
  link?: GlobalSidebarLink;
  // ... we may add other things here later
};