front matter option "displayed_sidebar" & "hide_sidebar"

🚀 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)

[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.

[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”.