Sidebar categories linking to a doc or category index page

[XavierNV]

🚀 Feature

Category in docs are only container for subitems (topics). But some help system enable category to be introductory topic to subitems (ie containing text that introduce the subitems or refers to subitems ie see also links to subtopic1, sub..)

Have you read the Contributing Guidelines on issues?

Yes

Motivation

Interested to use the Docusaurus Help System but before investing in it wan't to know the roadmap

Pitch

It's pretty useful. If you can read the introductory topic, you sometimes don't have to click/navigate to subtopics. It'a a better system than having a first topic (~overview) refering to following topics in a same level appearance > introductory topic has to be a level upper the subtopics..
Example of documentation with introductory topics :
https://www.gatsbyjs.org/docs/deploying-and-hosting/
https://www.innovasys.com/help/hs2019.1/authoringcontent.html
https://markdownmonster.west-wind.com/docs/

Hope my explaination is not too hard to understand..
Thanks to the docusaurus team for their work

Regards, Xavier

[hsiaoer]

+1 to this feature request. I have a case right now where I'm migrating docs over to docusaurus and we've set all nav items to be expanded by default.

themeConfig: {
    sidebarCollapsible: false,
}

Currently if you try clicking on the category item in the nav, nothing happens and it would be helpful to be able to add an optional link to a doc page on the category:

Example where introDoc.md is the doc when you click on the nav item.

{
        type: "category",
        label: "Introduction",
        rootItem: introDoc,
        items: [subdoc1, subdoc2]
}

[yangshun]

Some users want this behavior but some other users prefer that the category are just labels and not clickable. If we were to add support for this, we might need to change how the pure categories look, such that they don't look clickable.

[sladyn98]

@yangshun Is this still a starter issue to be worked on if yes I could maybe give it a shot.

[slorber]

Hey, didn't notice this issue, that also seems related to a more recent one: #3051

@sladyn98 there's ongoing work to be merged on the docs plugin + a few other important refactors I'd like to do.
This won't be time lost to have such a POC of this feature, and would help collect feedback, but just be aware that you might not be able to rebase it easily, and might need to re-open a brand new pull request 🤪

[slorber]

Raw thoughts but here's a possible api:

{
        type: "categoryDoc",
        label: "Introduction",
        id: "introDocId",
        items: [subdoc1, subdoc2]
}

Would render the introDocId doc.

{
        type: "categoryDoc",
        label: "Introduction",
        id: undefined, // on purpose
        items: [subdoc1, subdoc2]
}

Would render an automatically generated table of content of all the inner-tree of this category (we could later see how to make this view more useful by adding additional data to it, maybe a small doc summary or something)

[TomPeirs]

Is there any update on this feature?
Is there any proposed solution for now?
Currently I have a duplicate entry in my sidebar representing the category file. This of course looks a little bit ugly.

[slorber]

This is quite often requested (#3686) so we'll try to find a solution, but it will come after i18n support.

In the meantime, if someone wants to design the API surface and write an exhaustive RFC, so that it is flexible and suit all the use-cases reported, that would help.

The design of this feature is not so straightforward as we are not sure yet how it should behave regarding category collapsing.

[chrisdostert]

Just wanted to add that this is how the kubernetes.io docs work which to me are great. Would love to have this be available (if not default) behavior in docusaurus!

[ctlajoie]

I would definitely like to see this as well. I have encountered the requested functionality several times just today on different sites. In addition to the kubernetes.io docs mentioned by @chrisdostert:

• GitHub docs
• DITA docs

I like the sidebar behavior of the GitHub docs best (although the k8s docs operate similarly). It hides the sub-articles of the other categories that are not related to doc currently in view. I do not find this behavior confusing or annoying. It makes the sidebar easier to grok.

[slorber]

Thanks for showing some examples. We'll try to find an API that allows all these slightly different UX so that you can choose the one you want.

I like the sidebar behavior of the GitHub docs best (although the k8s docs operate similarly). It hides the sub-articles of the other categories that are not related to doc currently in view. I do not find this behavior confusing or annoying. It makes the sidebar easier to grok.

At the same time it's confusing if the item you click on immediately change position. I guess it's an acceptable tradeoff, but we should probably not enforce this specific UX.

[slorber]

FYI there's an existing PR, and also suggested an API here, curious to have your feedback on it: #3898 (comment)

[omry]

Thanks @slorber.
What I had in mind (which is in line with the examples provided by @ctlajoie, is to have a space to write an overview page for the category that would be linked to when clicking on the category itself.

This PR seems to be solving a different (if related) problem of how to minimize clicks in a world where you are forced to create an intro page as a subpage.

As a workaround it's a pretty clean one, but not exactly the request here.

[slorber]

@omry , you could create the overview md page, and make the category link to it?

module.exports = {
    docs: [
    {
      type: 'category',
      label: 'Docusaurus',
      link: {type: "doc", id: 'docusaurus-category-overview-doc'}
      items: ['introduction', 'design-principles', 'contributing'],
    },
    // ...
  },
};

Do you see a good reason for this category overview page to not be a regular doc?

[omry]

I think it should be a regular doc in the sense that I should be able to author it like any other doc.
This is mostly about the user experience: As a user I don't think of the content of the high level overview of a category as something at the same level as the items of the category.

Can you show me an example of what your above overview page looks like?
I have been adding an item to the list as an alternative for an index page. e.g:

[nascode]

Hi, i want to open doc when user click on a category in the sidebar. Looks like it's not supported yet.

Thus i try to create workaround for it by using first index of category item docs and modify sidebar component with sizzling.

You can see it on my repo https://github.com/nascode/example-docusaurus-v2-sidebar-category-doc

[lunchboxav]

that looks very helpful @nascode , thank you!

[slorber]

@omry what I understand is you want "tutorials" to link to the overview, instead of "Tutorials intro"

But isn't that exactly what I'm proposing to you?

module.exports = {
    docs: [
    {
      type: 'category',
      label: 'Tutorials',
      link: {type: "doc", id: 'tutorials-intro'}
      items: ['basic-tutorial', 'structured-config-tutorial'],
    },
    // ...
  },
};

Can you show me an example of what your above overview page looks like?

Exactly the same as your current intro page, it's just the sidebar that will be different

[omry]

I tried to modify my sidebar to this and was not successful (I kept getting parsing errors from the sidebar).
Here is my sidebar, Can you help me get on the right track?

[slorber]

@omry the code above is not implemented yet, it's just a possible API design we could use to implement this feature.

[omry]

Oh, I thought you meant that this was already supported somehow.

I think we are on the same page on the functionality aspects but let me repeat it to be sure:
What I would like is for the Tutorial category, when clicked would do two things:

1. change the content of the right pane to that of the page "Tutorials intro".
2. Expand the categories list (to contain the items Basic Tutorial and Structured Configs Tutorial).

This should also work when linking to https://hydra.cc/docs/tutorials/ (currently it results in 404).

Your proposed API design for dict describing the tutorials category above looks good to me.

I am assuming you are aware that currently the top level doc is a dict and not a list for some people (all?) as evident by my sidebar linked above and your suggestion is either a mistake or some other change that is planned:

my sidebar:

module.exports = {
    docs: {
       ...
    }

Your proposal:

module.exports = {
    docs: [
       ...
    ]
}

[TomPeirs]

What I think would be the desired effect is to simply be able to link a category to a markdown file itself
See example https://www.gatsbyjs.com/docs/recipes/

The following #2643 (comment) would not enable that as you would autogenerate some content, but it would be nice if we could define ourselves what to write on the intro/overview page of the cateogry

As mentioned by @hsiaoer , it would be helpful to be able to add an optional link to a doc page on the category:
Example where introDoc.md is the doc when you click on the nav item.
{ type: "category", label: "Introduction", rootItem: introDoc, items: [subdoc1, subdoc2] }

[slorber]

@dsmmcken it looks quite complicated to achieve what you want here because your cards are not really following a "normalized structure".

This top part could be achieved by adding some category custom props and plugging your own rendering logic:

---

The bottom part is more complex.

The first card leads to a doc, others are liking to headings/anchors... At some point, Docusaurus should be able to understand what it needs to create a card for.

What we'll do automatically (show cards for subcategory items, not headings) might not make sense in all use-cases.

---

But in the end, we should enable you to build your own index rendering logic and replace our own default logic.

With swizzle, you could be able to build your own rendering logic and create a sidebar category with a custom proprietary syntax, such as:

module.exports = {
  mySidebar: [
    {
      type: "category",
      label: "Tutorials",
      items: ["..."],
      link: { type: "generated-index" },
      customProps: {
        title: "Deephaven Tutorial",
        description: "Learn how Deephaven works",
        subtitle:
          "The goal of this tutorial is to help you create a mental model for how Deephaven works and to introduce you to its capabilities and workflows.",
        intro:
          "You will build analytics and applications with both updating (streaming) and static (batch) data sets, become familiar with the Deephaven IDE experience, apply your Python functions to your data, build a dashboard, create a notebook, and build and launch a stand-alone application. With a bit more time, you’ll then develop a Python client application that uses the API to receive data from your server application.",
        cards: [
          {
            title: "0. Quick Start",
            description:
              "Set up Deephaven in your Docker environment with pre-built images.",
            url: "/core/docs/tutorials/quickstart/"
          },
          {
            title: "1. Ingest static data",
            description:
              "Import CSVs from URLs. Read an example CSV and Parquet file..",
            url: "/core/docs/tutorials/tutorial/#1-ingest-static-data"
          }
          // ... other cards here
        ]
      }
    }
  ]
};

Does it make sense?

Not sure it would be significantly simpler than linking to a custom doc though (or using an index.md or README.md which we'll support).

At best, it can help you normalize all those index pages under a unified API so that you are sure they are all consistent with each others

---

Something to consider with cards, is maybe including the description from the front-matter as well on the card.

Yes, I'll add the doc item description in default rendered cards (todo):

[slorber]

If you have any feedback to share, on what you see here, now is a good time:

• Category linking to doc: https://deploy-preview-5830--docusaurus-2.netlify.app/docs/next/api/plugins/
• Category linking to automatically generated index: https://deploy-preview-5830--docusaurus-2.netlify.app/docs/next/category/guides

I'm in the process of making this robust, tested and documented, so let me know if you have any UX feedback

(the only missing UX is the ability to collapse a category)

[dsmmcken]

That looks pretty good. I think linking to a page, or auto generated will work for most people.

Something I find awkward is not being able to collapse an opened category. If I open a category in the middle and it's giant, then I want a doc in the category after, it is difficult to have to scroll way past it. Should you still be able to collapse a category if it's active, by clicking it? Maybe the icon can performs that action? I don't know, but that bit feels off.

My page having weird links to headings is actually just a temporary solution, we intend them to be separate pages (our code snippets are auto extracted, tested, run, and then automatically inject their output back into the page, but we haven't create the ability to have snippets depend on other pages yet, so they are for now on one page).

If possible, it would be nice if you could also fetch the card data only somehow, where I could have an index page, but then still render cards on it as well.

some-category-doc.md

---
etc
---

my custom intro or whatever markup here

<MyCustomCardComponent cards={some-magic-way-to-have-card-data-here} />

Kinda like how you can add a component to a page.

[Josh-Cena]

Something I find awkward is not being able to collapse an opened category.

Yep, it's actually blocked by an upstream dep: facebookincubator/infima#188 (it's also developed by us anyways, so not so much trouble, just that the fix isn't in place yet)

If possible, it would be nice if you could also fetch the card data only somehow, where I could have an index page, but then still render cards on it as well.

+1. And I do have an idea of how to implement this, let's see if we want to add that in this PR or raise a subsequent PR because this one is getting big

[TomPeirs]

Hi @slorber and @Josh-Cena
Thank you for working on this interesting feature.

My input would be to make the cards render similar to an admonition, as I find contrast-wise they seem to adhere more to W3C accessibility standards to me.
The hover effect and the cursor handling is nice, but the border shadow hurts my head a little.

And furthermore facebookincubator/infima#188 is relevant to make the collapsible working

[Josh-Cena]

My input would be to make the cards render similar to an admonition, as I find contrast-wise they seem to adhere more to W3C accessibility standards to me.

I guess you are talking about the same problem as the box shadow. See facebookincubator/infima#187. I don't think the current design is problematic but certainly we can sharpen the shadow when not hovered.

[TomPeirs]

My input would be to make the cards render similar to an admonition, as I find contrast-wise they seem to adhere more to W3C accessibility standards to me.

I guess you are talking about the same problem as the box shadow. See facebookincubator/infima#187. I don't think the current design is problematic but certainly we can sharpen the shadow when not hovered.

Indeed, that would work.

[TomPeirs]

@Josh-Cena @slorber
One more thing to consider for Card Icons.
The sidebar object can take the following : doc, ref, link, category.
In the netlify preview we can see the icons for a doc and a category, and I was wondering if you considered also Link?

Perhaps we could add a little bit more spacing between the Title and the Icon of a card?

Would there be a possibility to add a customization option to assign those icons/svgs for the card icons?

[Josh-Cena]

Perhaps we could add a little bit more spacing between the Title and the Icon of a card?

I personally think the spacing is good...

Would there be a possibility to add a customization option to assign those icons/svgs for the card icons?

If you have differing design ideas you can likely re-implement your own index page through swizzling. (And we will try to make it as convenient as possible.) We would likely not add options for every detail.

In the netlify preview we can see the icons for a doc and a category, and I was wondering if you considered also Link?

Indeed, links, unsurprisingly, have the icon 🔗.

[TomPeirs]

Perhaps we could add a little bit more spacing between the Title and the Icon of a card?

I personally think the spacing is good...

Would there be a possibility to add a customization option to assign those icons/svgs for the card icons?

If you have differing design ideas you can likely re-implement your own index page through swizzling. (And we will try to make it as convenient as possible.) We would likely not add options for every detail.

In the netlify preview we can see the icons for a doc and a category, and I was wondering if you considered also Link?

Indeed, links, unsurprisingly, have the icon 🔗.

Oke thank you ;-) seems that everything is considered.

[slorber]

Yes, we'll allow collapsing a category

External links have a different icon, this can be seen here: https://deploy-preview-5830--docusaurus-2.netlify.app/tests/docs/category/tests/

If possible, it would be nice if you could also fetch the card data only somehow, where I could have an index page, but then still render cards on it as well.

I don't understand what this means sorry 😅

Perhaps we could add a little bit more spacing between the Title and the Icon of a card?
Would there be a possibility to add a customization option to assign those icons/svgs for the card icons?

We'll likely improve the design and add customization options later. Here I'm mostly focusing on the initial MVP with the UX and a good extensible public API that we can improve later.

Note that these theme components are well encapsulated and easy to customize with a swizzle.

---

Thanks for your feedback, which is mostly about design and "shortcut" options, we can improve all that incrementally from the current state later in subsequent PRs, and in the meantime using swizzle is likely a good enough workaround until we figure out the most wanted customization apis.

[Josh-Cena]

If possible, it would be nice if you could also fetch the card data only somehow, where I could have an index page, but then still render cards on it as well.

@slorber By that he means, you have a normal doc page as index page, but inject the category items in it as JSON so it can be rendered somewhere in the middle of the page, kind of like the TOCInline where we have a global toc export to do this.

My idea would be to inject this in MDXProvider

[slorber]

Oh I see, something like this?

It's already technically possible atm using hooks in the MDX doc, but probably not with the most intuitive API. We can figure out later how to add MDX shortcodes for that.

## Category Content

import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>

[slorber]

PR and UX ready for a final review!

Unless there's any pushback, this is going to be merged tomorrow!

#5830

Test URLs:

• https://deploy-preview-5830--docusaurus-2.netlify.app/docs/next/category/getting-started
• https://deploy-preview-5830--docusaurus-2.netlify.app/docs/next/category/guides
• https://deploy-preview-5830--docusaurus-2.netlify.app/docs/next/markdown-features/
• https://deploy-preview-5830--docusaurus-2.netlify.app/tests/docs/category/tests

Docs:

• Category links (doc, generated-index)
• Category index.md convention
• docCategoryGeneratedIndexComponent option

---

Please share your last feedback asap

[dsmmcken]

Is it easy to change/remove the icons, or would I have to swizzle the component for that?

[Josh-Cena]

Is it easy to change/remove the icons, or would I have to swizzle the component for that?

@slorber Is it possible to popularize the idea of CSS ::before pseudoelements for these icons?

[seanbrakefield]

I’ve been following the progress of this for a while now, and I love how this is forming. Really great work!

Request:
Can you close the Table of Contents panel when tapping the Category item (that has a page) on the mobile version? Currently, that panel stays open which makes it seem like nothing has occurred.

[slorber]

Is it easy to change/remove the icons, or would I have to swizzle the component for that?

@slorber Is it possible to popularize the idea of CSS ::before pseudoelements for these icons?

For now you can swizzle the DocCard component

We don't have yet a good way to manage theme icons, we'll try to normalize how we handle icons in themes as part of #5865 and make sure that overriding an icon is consistent for all the existing use-cases of the theme.

If you have a better icon/design we can also improve our current design. Feel free to override DocCard in userland for now, show us the result, and eventually if the design is better we can make it the default later.

---

Can you close the Table of Contents panel when tapping the Category item (that has a page) on the mobile version? Currently, that panel stays open which makes it seem like nothing has occurred.

Yes, also noticed that ;) this has been fixed

[slorber]

This has been published in canary (0.0.0-4241) and scheduled for a release next week

Please give it a try and tell us if it works fine ;)

[SivertGullbergHansen]

Hey guys 😄
I've been struggling to find the option to enable this?
I didn't want to bother reading through all these comments, therefore I am asking :)

I also couldn't find anything related to it in your docs

[Josh-Cena]

@SivertGullbergHansen

• https://docusaurus.io/docs/sidebar/items#category-link
• https://docusaurus.io/docs/sidebar/autogenerated#category-item-metadata

[bfelbo]

If you can read the introductory topic, you sometimes don't have to click/navigate to subtopics. It'a a better system than having a first topic (~overview) refering to following topics in a same level appearance > introductory topic has to be a level upper the subtopics.. Example of documentation with introductory topics : https://www.gatsbyjs.org/docs/deploying-and-hosting/

Interestingly, Gatsby actually moved away from this style. My guess would be that it's because readers might miss that they can click on the category sidebar to read info. Readers might sometimes expand the category using the arrow instead, thereby missing crucial introductory info. This can also happen if the reader opens a category subpage from an external link, in which case it's unlikely they'll know to click the category in the sidebar since it's already expanded.

I'd argue that one can achieve the best of both worlds by making any clicks to the category redirect the reader to the intro subpage. That way, it's still a quick experience (same # of clicks), but makes the intro information explicit. I've created #8833 to add support for this :)