Make all front matter used by the theme accept `desktop` and `mobile`

[Josh-Cena]

🚀 Feature

Front matter should accept both a simple option:

---
hide_table_of_contents: true
---

Or an object:

---
hide_table_of_contents:
  mobile: true
  desktop: false
---

Have you read the Contributing Guidelines on issues?

Yes

Has this been requested on Canny?

No

Motivation

Extracted from #5686.

API Design

Front matter has two uses: they are either picked up by the plugin as metadata, or by the theme to render certain elements, but usually not both. A non-exhaustive list:

• sidebar_class_name
• hide_title
• hide_table_of_contents
• hide_sidebar (not implemented yet)
• hide_pagination (not implemented yet, I think this can be useful to add? Hiding pagination at theme level instead of pagination_next: null, which disables pagination at plugin level)
• toc_min_heading_level
• toc_max_heading_level

This permits us to render different layouts on different screen sizes, while not altering any UX (e.g. we don't allow displaying different sidebars because that's passed on by the plugin, neither do we allow setting a different group of authors).

In addition, different theme implementations can even use other key names, like tablet, 1440, 997, etc. So during validation, we should allow any string keys.

[namangirdhar16]

hi @Josh-Cena i would like to work on this issue. Please assign this to me.

[Josh-Cena]

Sorry, this is already taken by @cerkiewny, I should have marked that😅

[Josh-Cena]

@namangirdhar16 In case you are looking for something to contribute, would you want to take a look at this? https://github.com/facebook/docusaurus/discussions/5749 You can re-design the Details component in theme-classic.

[slorber]

Make all front matter used by the theme accept desktop and mobile

As explained in https://github.com/facebook/docusaurus/pull/5854#discussion_r741885050, I'd rather not introduce this to ALL frontmatter, but only if there's a strong use-case.

Supporting this config adds complexity to avoid layout shifts

toc_min_heading_level

If we want a TOC to have different heading levels for mobile/desktop without hydration layout shifts, this means rendering it twice and adding a mediaquery to each TOC so that only one is displayed at the same time. This increases the HTML file size and code complexity for a questionable feature that I feel we don't really need. If the user is using a simple boolean instead of {mobile: boolean, desktop: boolean} we can optimize by rendering only once the TOC, and the HTML wouldn't grow for most users, but this still complicates our codebase for little value.

So I'd rather collect first strong use-cases for doing something differently on mobile/desktop, and implement each use-case separately

[Josh-Cena]

Makes sense yeah, let's do it for hide_sidebar and hide_table_of_contents for now since we do have use-cases. I do feel like sometimes we should render fewer heading levels on mobile considering it takes up scroll height but... until someone asks for it

[slorber]

Makes sense yeah, let's do it for hide_sidebar and hide_table_of_contents for now since we do have use-cases.

Agree for these 2 configs.

Note that the TOC is a special case, and a good API might be more complex to support all use-cases:

• there's the right TOC, and it probably doesn't make any sense to render on mobile (where could we render it?)
• there's the collapsible TOC, and there may be value rendering it in desktop too? I don't know

do feel like sometimes we should render fewer heading levels on mobile considering it takes up scroll height but... until someone asks for it

Oh actually I'm a bit wrong above and the TOC is rendered differently on mobile/desktop, so technically it's quite similar to the sidebar case and we could adjust the TOC heading levels config according to the right TOC vs inline TOC, and it shouldn't introduce layout shifts because we already handled those mediaqueries

[techieeliot]

The comments on this issue are stale from last Hacktoberfest? Is the issue still relevant and claimed @slorber?

I just found this repo from a dev.to article, so I'll head over to your discord to see some help getting started if not here on this issue then another one.

[sidharthk9]

Checked through the discussion in #5686 and the ensuing work through #5782 and #8146. Looks like the deployed feature covered this issue, so does it have to remain open?

[slorber]

@sidharthk9 I don't think we support this kind of front matter yet, which this issue is about:

---
hide_table_of_contents:
  mobile: true
  desktop: false
---

@Josh-Cena curious: who came up with the need for this?

Is this a "cool feature we could have" or something someone really came up with a use-case for?

I think we could close this until someone has a concrete use-case for it.

[Josh-Cena]

Frankly I don't remember at this point... Pretty sure someone asked on Discord so I opened this issue. However, because TOC & sidebar are not rendered on mobile on startup, I don't think their customizations would lead to FOUC or the like.

[slorber]

will close this for now and we'll see if the need comes again