Docusaurus: 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: https://github.com/facebook/docusaurus/issues/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 (https://github.com/facebook/docusaurus/issues/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: https://github.com/facebook/docusaurus/pull/3898#issuecomment-742638270

[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 https://github.com/facebook/docusaurus/issues/2643#issuecomment-661058279 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]

@omry yes we agree

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

You can already use slug: /docs/tutorials on your existing category intro doc for that

I am assuming you are aware that currently the top level doc is a dict and not a list for some people

As documented, there are 2 syntaxes (shorthand/dictionary, expanded/list) but they are equivalent, it's just a shortcut we created. Also you'll have to use the expanded form if you want more options like the one we are discussing here, as the shorthand is just categoryName -> subItems and can't pass more config

---

@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/

Yes, this is exactly what my API description above would solve

The following #2643 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 category

I don't understand, it's what I suggest to do: we assign a docId to a category instead of generating automatically the category page when we write such config:

It's your responsibility to write an intro/category doc with id: tutorials-intro here, we won't auto-generate it.

This is very similar to what you suggest, except we didn't use the same name/api surface.
Replace rootItem: "docId" by link: {type: "doc", id: "docId"} for better extensibility)

[omry]

Thanks @slorber

You can already use slug: /docs/tutorials on your existing category intro doc for that

1. Can you point to an example?
2. This will still be needed once you support sidebar category doc?

[slorber]

The example is just what I gave you, just try this frontmatter and see how
it impacts your doc url
https://v2.docusaurus.io/docs/docs-introduction/

The presence of a doc in a sidebar (either as a regular doc or a caterory
doc) does not affect its url in anyway. Only the slug/id/filename do.

You are free to choose the exact url you want for all your docs using the
slug frontmatter

Le ven. 18 déc. 2020 à 04:31, Omry Yadan [e-mail] a
écrit :

Thanks @slorber https://github.com/slorber

You can already use slug: /docs/tutorials on your existing category intro
doc for that

1. Can you point to an example?
2. This will still be needed once you support sidebar category doc?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/facebook/docusaurus/issues/2643#issuecomment-747846079,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AAFW6PUXZH75YONEJI56WQLSVLEI7ANCNFSM4MOIT2IA
.