Have breadcrumbs link to the first document in a category if the category itself is not a link

[patrys]

As the title says, it would be nice to have the option of breadcrumbs always linking somewhere.

We have big API reference pages, and it does not make sense to try to generate index pages for them. But it also means that breadcrumbs appear broken as nothing is clickable.

A similar problem appears if you try to autogenerate sidebars from a multi-level directory structure, it correctly populates the sidebar but makes breadcrumbs unusable as none of the categories are pages themselves.

[patrys]

Here's an example of docs generated using GraphQL-Markdown:

https://docs.saleor.io/docs/3.x/api-reference/enums/address-type-enum

[slorber]

A similar problem appears if you try to autogenerate sidebars from a multi-level directory structure, it correctly populates the sidebar but makes breadcrumbs unusable as none of the categories are pages themselves.

Note: intermediate breadcrumb items are just sidebar categories. If you make sidebar categories clickable, the breadcrumbs will be clickable as well. All the solutions above focus on making the categories clickable, as both are linked. You can as well drop a index.md in a subfolder and the category would become clickable.

[patrys]

What would you put in an index file for the example I linked? It does not make sense to generate cards for all of the entries.

As the sidebar uses an auto-generated tree, I also don’t see a way to add a link unless it’s supported by _category_.json.

[slorber]

What would you put in an index file for the example I linked?

You put whatever you want in this file, it's up to you. You can write an intro text for Enums without rendering cards.

It does not make sense to generate cards for all of the entries.

It doesn't make sense either to have the category to link to its first doc in all cases. In particular for deeply nested categories this might be confusing to have the top-level category to link to a deeply nested doc (ie the first doc being in a sidebar tree). At least it's not a very intuitive default behavior that's why I prefer it to be opt-in.

---

As the sidebar uses an auto-generated tree, I also don’t see a way to add a link unless it’s supported by category.json.

Indeed, it is supported:

https://docusaurus.io/docs/next/sidebar/autogenerated#category-item-metadata

[patrys]

Thanks, I was not aware of that! In this case the only missing bit is being able to say “first child” without having to name a specific document.

[slorber]

Technically you can customize the sidebar generator so that it automatically links all categories it generates to their first docs child :)

https://docusaurus.io/docs/next/sidebar/autogenerated#customize-the-sidebar-items-generator

function linkCategoriesToFirstChild(items) {
  // TODO do whatever you want here
}

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
          const sidebarItems = await defaultSidebarItemsGenerator(args);
          return linkCategoriesToFirstChild(sidebarItems);
        },
      },
    ],
  ],
};