Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
Josh-Cena opened this issue Oct 28, 2021 · 11 comments 路 May be fixed by #5854
Closed

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

Josh-Cena opened this issue Oct 28, 2021 · 11 comments 路 May be fixed by #5854
Labels
closed: wontfix A fix will bring significant overhead, or is out of scope (for feature requests) feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future.

Comments

@Josh-Cena
Copy link
Collaborator

Josh-Cena commented Oct 28, 2021

馃殌 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.

@Josh-Cena Josh-Cena added feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. good first issue If you are just getting started with Docusaurus, this issue should be a good place to begin. difficulty: starter Issues that are starter difficulty level, e.g. minimal tweaking with a clear test plan. labels Oct 28, 2021
@namangirdhar16
Copy link

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

@Josh-Cena
Copy link
Collaborator Author

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

@Josh-Cena Josh-Cena added the status: claimed Issue has been claimed by a contributor who plans to work on it. label Oct 29, 2021
@Josh-Cena
Copy link
Collaborator Author

@namangirdhar16 In case you are looking for something to contribute, would you want to take a look at this? #5749 You can re-design the Details component in theme-classic.

@slorber
Copy link
Collaborator

slorber commented Nov 3, 2021

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

As explained in #5854 (comment), 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
Copy link
Collaborator Author

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
Copy link
Collaborator

slorber commented Nov 3, 2021

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
Copy link

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
Copy link

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
Copy link
Collaborator

slorber commented Apr 28, 2023

@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
Copy link
Collaborator Author

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
Copy link
Collaborator

slorber commented Sep 25, 2023

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

@slorber slorber closed this as not planned Won't fix, can't repro, duplicate, stale Sep 25, 2023
@Josh-Cena Josh-Cena added closed: wontfix A fix will bring significant overhead, or is out of scope (for feature requests) and removed good first issue If you are just getting started with Docusaurus, this issue should be a good place to begin. difficulty: starter Issues that are starter difficulty level, e.g. minimal tweaking with a clear test plan. status: claimed Issue has been claimed by a contributor who plans to work on it. labels Sep 25, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
closed: wontfix A fix will bring significant overhead, or is out of scope (for feature requests) feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants