front matter option "displayed_sidebar" & "hide_sidebar"

[Josh-Cena]

🚀 Feature

Have you read the Contributing Guidelines on issues?

Yes

Has this been requested on Canny?

No

Motivation

We have two item types: doc which creates both the sidebar association and the link, ref which creates just the link but not association (the sidebar will not show up on that page). We naturally want a third: association that creates the association but not the actual link.

Use-case: home pages of docs sites would use the sidebar as navigation, but itself shouldn't necessarily appear in that sidebar (typically we go back by clicking the logo or using a navbar link).

API Design

A new sidebar item type association would be sufficient. It might still take all the props of doc or ref for uniformity (we won't throw during validation), but they don't do anything.

The association item can be declared anywhere in the sidebar, because it doesn't go into the rendered structure.

Have you tried building it?

It would literally be just 20 lines of code in the doc metadata generation logic. But I'll be implementing this after the category index page thing (or at least after #5678)

[slorber]

So you mean the home doc would display a sidebar and a next button, but there wouldn't be a "home" link in the sidebar?

I'm not against this, just wondering how useful it would be and if people will be understand this feature. (Refs are already not widely used afaik, and our doc about them was a bit confusing)

---

Some questions to figure out if we really need this:

• Who expressed this need exactly?

• Why having a custom landing page isn't better?

• Why hiding the home doc from the sidebar matter?

• Are we talking about non-dev users that can't write any React at all but still want to use Docusaurus?

• Are there any other use-cases than the site landing page to consider?

• Is association the best name? I'm already not a fan of ref, it's not very intuitive and we don't really understand that it is about a doc without reading the documentation.

[Josh-Cena]

Who expressed this need exactly?

Me, plus three users on Discord.

Why having a custom landing page isn't better?

It's hard to describe. Look at this page: https://docs.luxalgo.com/ The need is that:

• On desktop, the doc sidebar shouldn't be shown;
• On mobile, the sidebar should be shown when clicking on the hamburger, instead of the main navbar (because... my client thinks that makes navigation less confusing).

Therefore, this page has to be part of the docs plugin (which I implemented by importing a React component into the MD page), or else it won't know about the docs sidebar. On the other hand, it should do absolutely nothing with that sidebar—the only thing it should do is getting itself registered.

I don't see how this use-case can be realized without sufficient hacking (I hope I'm already one of the guys most familiar with the internal details). Currently I swizzled DocSidebar and hided any link with label "Home", but that's straight hack.

Is association the best name? I'm already not a fan of ref, it's not very intuitive and we don't really understand that it is about a doc without reading the documentation.

ref is a bad name, particularly because the documentation is already unclear on this. But if we stress on the idea of "association", the corresponding item type should be easy to understand. For a normal user, it doesn't appear that a sidebar is an auxiliary (metadata) of the doc—they would think the docs belong to a sidebar. We need to tweak that understanding.

[slorber]

I'm just asking because I don't like adding features without understanding better the use-case :)

This use-case seems reasonable to me and we should try to support this.

What I don't like:

• Ref is confusing, the API could be better, like sidebar: false on the doc item instead: good time to rethink this API overall
• A sidebar item can be added inside a category. If you want to create an association, where do you add it exactly in the sidebars file? You can add it at the top, or inside a category, and it would give the same results: this is weird
• If you create an association, the sidebar should render on both mobile+desktop, not just mobile => does not solve your use-case

What about adding sidebar: boolean | string on both the sidebars.js doc item type, and some extra doc frontmatter?

We could deprecate the ref type, add a more powerful/generic API that solves all the use-cases at once?

• Default: {type: "doc", sidebar: true}: doc link appear in sidebar + parent sidebar is rendered for it
• Ref: {type: "doc", sidebar: false}: doc link appear in sidebar + but parent sidebar is not rendered for it
• New: {type: "doc", sidebar: "sidebarName"}: not sure it makes much sense to but we could add that later if needed (somehow a shortcut for both "ref" + "association" in a single sidebar item 😅 )
• frontMatter.sidebar_deskop = false + frontMatter.sidebar_mobile = 'sidebarName' => solve your use-case?

[Josh-Cena]

If you create an association, the sidebar should render on both mobile+desktop, not just mobile => does not solve your use-case

Yeah, my use-case may not be the best to illustrate this API.

So adding a doc in a sidebar creates a two-way binding: sidebar includes the doc link, doc page renders the sidebar. ref removes the doc-to-sidebar binding (doc page doesn't render sidebar), and association removes the sidebar-to-doc binding (sidebar won't include the link). I think this explanation is good enough for the documentation purpose, but ref itself is a bad name, yeah

frontMatter.sidebar_deskop = false + frontMatter.sidebar_mobile = 'sidebarName'

I thought about that, but this means the sidebar keys are no-longer irrelevant on the user side. But it certainly makes sense 👍

{type: "doc", sidebar: "sidebarName"}

Won't that create two sidebar associations, just like declaring the same doc in two sidebars? What's the use case?

[Josh-Cena]

Oh, and I think your API would also handle autogenerated items pretty nicely. I like the sidebar_desktop and sidebar_mobile front matter idea.

[slorber]

but this means the sidebar keys are no-longer irrelevant on the user side.

I don't understand this, can you explain?

{type: "doc", sidebar: "sidebarName"}

Won't that create two sidebar associations, just like declaring the same doc in two sidebars? What's the use case?

For me, it would add a link to the parent sidebar, and bind to the sidebarName (so it's a shortcut for both ref + association => confusing and not really useful to add. IMHO)

---

So, if I understand we agree on:

• adding sidebar_deskop + sidebar_mobile as frontMatter to solve your use-case?
• eventually, refactor ref into a better API (breaking change, in another PR)

Your use-case would be solved by:

• not adding homepage to sidebars.js
• using sidebar_mobile: 'sidebarName' in frontMatter

right?

[Josh-Cena]

The keys tutorialSidebar and apiSidebar are sidebar technical ids and do not matter much.

Now they do matter :P

And yes, your summary is what I'm thinking of—using front matter to create associations-only, and use sidebars.js to create actual links, optionally de-generating the implicit association with sidebar: false (actually let's consider a better name. Maybe displaySidebar: false?). It all makes sense.

[Josh-Cena]

For me, it would add a link to the parent sidebar, and bind to the sidebarName (so it's a shortcut for both ref + association => confusing and not really useful to add. IMHO)

Mmmm, {type: 'doc', id: 'my-doc'} already creates both ref and association. Consider this:

const sidebars = {
  sidebarA: [
    {type: 'doc', id: 'my-doc'},
  ],
  sidebarB: [
   {type: 'doc', id: 'doc2', sidebar: 'sidebarA'},
  ],
};

From your description, you are saying that sidebarA would be displayed on doc2 instead of doc2, but sidebarB would be the one containing the link doc2? This would be an alternative to the more verbose steps of

• sidebar_mobile: sidebarA, sidebar_desktop: sidebarA in front matter, and
• displaySidebar: false in that doc2 sidebar item

I don't have much objection to that API, but it's pretty confusing IMO, and doesn't look like a natural derivative of the displaySidebar API (maybe because you used the generic identifier sidebar but I prefer a clearer displaySidebar)

[slorber]

Now they do matter :P

yes 🤪

Maybe displaySidebar: false?)

👍 better

---

I'm saying:

const sidebars = {
  sidebarA: [
    {type: 'doc', id: 'my-doc', sidebar: "sidebarB"},
  ],
  sidebarB: [
  ],
};

Would be the same as:

const sidebars = {
  sidebarA: [
    {type: 'ref', id: 'my-doc'},
  ],
  sidebarB: [
    {type: 'association', id: 'my-doc'},
  ],
};

And it would only be a shortcut for a use-case that does not really make much sense in the first place, so I'd rather not do this (and I think we agree that type: "association" is not a good thing anyway.

---

Eventually, we could have a more convenient md frontmatter syntax:

---
sidebar: sidebarA
---

or

---
sidebar: 
  mobile: sidebarA
  desktop: null
---

I don't think many will want to hide the sidebar just on desktop (like you do) so maybe we shouldn't complicate the API for the most common use-case and just provide a sidebar frontmatter?

[Josh-Cena]

Actually, I think there are many other layout-related metadata that can accept desktop + mobile (hide_table_of_contents for example). This would be a good place to start.

However, as I looked through relevant source code, I think it'll make more sense if we make two front matter options: hide_sidebar and sidebar. The former will accept screen-size-based config while the latter just associates the doc to a sidebar. This ensures that we don't complicate the doc's metadata and separates "data" from "presentation".

[slorber]

The former will accept screen-size-based config

You mean hide_sidebar: 640px or hide_sidebar: mobile?

Can this make sense for any use-case?

---
sidebar: 
  mobile: sidebarA
  desktop: sidebarB
---

[Josh-Cena]

I mean,

---
sidebar: sidebarA
hide_sidebar:
  mobile: true
  desktop: false
---

Or:

---
sidebar: sidebarA
hide_sidebar: true
---

Assigning different sidebars on desktop and mobile makes navigation quite confusing IMO, and it also makes the doc's metadata unnecessarily different from before.

[slorber]

Agree.

Also the concept of "mobile/destop" is theme-specific (another theme might decide to use 3 breakpoints). I wonder if it's a good idea to include this notion inside docs plugin core: it may be better to handle this frontmatter only inside the theme (which can be annoying for hide_sidebar normalization)

[Josh-Cena]

Also the concept of "mobile/destop" is theme-specific (another theme might decide to use 3 breakpoints). I wonder if it's a good idea to include this notion inside docs plugin core: it may be better to handle this frontmatter only inside the theme (which can be annoying for hide_sidebar normalization)

Yes, we are. Once we split the front matter into sidebar and hide_sidebar, the latter will only be picked up by the theme while ignored by the docs plugin, and it will be up to the theme to decide what to use: one can use mobile and desktop, another may pick up an additional pad, another may be using different terms... That wouldn't be much problem.