Make theme desktop responsive breakpoint configurable

[slorber]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

See

• feat(theme-common): Get desktopThresholdWidth from docusaurus config #9261
• refactor(theme-common): allow optional desktopBreakpoint param in useWindowSize #9335

People want to be able to configure easily the 996px desktop breakpoint.

It's not easy currently because the value is hardcoded in both the JS side, but also CSS side (inside Infima directly), cf my comment #9261 (comment)

We should make this easier to achieve without requiring swizzling.

Self-service

• I'd be willing to do some initial work on this proposal myself.

[jasikpark]

Is there a recommended path to customizing the breakpoint where the nav switches from desktop to mobile? It seems I'd have to swizzle the navMobileSidebar.tsx hooks to do that.

[slorber]

No we don't have a way to achieve that easily unfortunately, you need to override all the CSS media queries and React hooks we have, exhaustively

One thing that makes it a bit harder is that it's not possible to use dynamic variables in media query ranges: https://bholmes.dev/blog/alternative-to-css-variable-media-queries/

Having things being packaged in another separate CSS package (Infima) doesn't make it easier.

[neoakris]

@slorber
I've learned several swizzle based customizations (relevant to this topic), but I think I may have also identified a bug. Can you comment on if this would warrant creating a bug report?

Context:
I had been thinking about posting a bug report, because I after dedicating ~5 days of tinkering across 6 weekends, I've come to the conclusion that while most things related to this "desktop responsive breakpoint" threshold are customizable with the swizzle/css override method, but one of the more impactful to user experience one's isn't.
(I love the right hand ToC functionality, for UX, and it doesn't seem to be tweakable with swizzling/css overrides.)

Example of threshold related things that are possible to customize (in docusaurus 3.6.3):

• Note: many of the Editable references I'll mention showed up by running this in the same dir where npx docusaurus start would be run (and selecting (with TypeScript Eject YES at the prompt):
  • npm run swizzle @docusaurus/theme-classic DocItem
  • npm run swizzle @docusaurus/theme-classic DocRoot
  • npm run swizzle @docusaurus/theme-classic DocSidebar
• 1st Customization: More space can be given to Desktop View's right hand ToC text
  • overriding swizzled component doesn't seem to work, global css also needs override, which requies update to docusaurus.config.js that's well documented, 25% is the default value, adjusting it adjusts the width of the TOC & has an important side effect of adjusting the threshold, when I changed it to 35% my desktop threshold changed to 898px.
  • By overriding global css (:
    /src/css/custom.scss

    .col--3 {
    --ifm-col-width: calc(25%);
    }
    

• 2nd Customization: Always hide the mobileToC (even in mobile view)
  • By editing line 1 of:
    /src/theme/DocItem/TOC/Mobile/styles.module.css
    to: @media (min-width: 1px) {
• 3rd Customization: Always show the mobileToC (even in desktop view) alongside desktop style right hand ToC
  • By editing line 1 of:
    /src/theme/DocItem/TOC/Mobile/styles.module.css
    to: @media (min-width: 3000px) {
• 4th Customization: have Desktop View's left docs sidebar to always show up in mobile view.
  • By editing;
    • line 6 of:
      /src/theme/DocRoot/Layout/Main/styles.module.css
      to: @media (min-width: 1px) {
    • line 10 of:
      /src/theme/DocRoot/Layout/Sidebar/styles.module.css
      to: @media (min-width: 1px) {
    • line 1 of:
      /src/theme/DocRoot/Layout/Sidebar/ExpandButton/styles.module.css
      to: @media (min-width: 1px) {
    • line 1 of:
      /src/theme/DocSidebar/Desktop/styles.module.css
      to: @media (min-width: 1px) {
    • line 11 of:
      /src/theme/DocSidebar/Desktop/CollapseButton/styles.module.css
      to: @media (min-width: 1px) {
    • line 1 of:
      /src/theme/DocSidebar/Desktop/Content/styles.module.css
      to: @media (min-width: 1px) {
    • line 11-12 of:
      /src/theme/DocSidebar/index.tsx
      to: const shouldRenderSidebarDesktop =
windowSize === 'desktop' || windowSize === 'ssr' || windowSize === 'mobile';

---

• A 5th customization of getting Desktop View's Right Hand ToC to show up in mobile view doesn't seem possible, based on tons of tinkering/even when overriding things. (sadly this is the UX feature I care about most for mobile view's landscape mode.)
  • Here's what I tried which I though would have been enough, but isn't, and makes me question if this is a bug:
    • potential bug, doesn't have expected effect of rendering desktop TOC always:
      line 31 of:
      /src/theme/DocItem/Layout/index.tsx
      to: canRender && (windowSize === 'desktop' || windowSize === 'ssr' || windowSize === 'mobile') ? (
    • ^-- This combined with all kinds of permutations of @media css overrides. (I've also tried editing the index.tsx in other ways, but to no benefit.)

---

^-- I'm not sure if the inability to customize docusaurus using swizzle so desktop ToC shows up in mobile view would be a bug or feature request, given the other things are possible I lean toward bug. Thoughts?

Also out of curiousity, this larger issue of customizable breakpoints looks hard/like it'd take a long time to sort out. Any guess on how hard updating logic to allow desktop ToC show up in mobile via swizzle/css edits would be?

[slorber]

@neoakris I'm not sure why we can consider this as a "bug", it's just not something we support.

You can render the desktop top with swizzle and custom CSS, however it won't probably render in the place you expect. Now it's your responsibility to move nodes around to fix your mobile layout and figure a way to include the TOC.

Here's a patch to achieve that:

diff --git a/packages/docusaurus-theme-classic/src/theme/DocItem/Layout/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocItem/Layout/index.tsx
index 138b6ad45f..3a8296d7f8 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocItem/Layout/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocItem/Layout/index.tsx
@@ -27,7 +27,7 @@ import styles from './styles.module.css';
  */
 function useDocTOC() {
   const {frontMatter, toc} = useDoc();
-  const windowSize = useWindowSize();
+  const windowSize = useWindowSize({desktopBreakpoint: 1});
 
   const hidden = frontMatter.hide_table_of_contents;
   const canRender = !hidden && toc.length > 0;
@@ -39,6 +39,8 @@ function useDocTOC() {
       <DocItemTOCDesktop />
     ) : undefined;
 
   return {
     hidden,
     mobile,
diff --git a/packages/docusaurus-theme-classic/src/theme/TOC/styles.module.css b/packages/docusaurus-theme-classic/src/theme/TOC/styles.module.css
index 4b6d2bcc65..20594f2bb1 100644
--- a/packages/docusaurus-theme-classic/src/theme/TOC/styles.module.css
+++ b/packages/docusaurus-theme-classic/src/theme/TOC/styles.module.css
@@ -11,13 +11,3 @@
   position: sticky;
   top: calc(var(--ifm-navbar-height) + 1rem);
 }
-
-@media (max-width: 996px) {
-  .tableOfContents {
-    display: none;
-  }
-
-  .docItemContainer {
-    padding: 0 0.3rem;
-  }
-}

[neoakris]

Thanks for spending some time to share confirmation about "I'm not sure why we can consider this as a "bug", it's just not something we support."
between swizzling being supported, swizzling working for other cases, and talk of a configurable break point I thought it was at least worth asking about.

Also thanks for sharing patch ideas, the one you found is one I've discovered once before / I've been able to get the desktop ToC to show up at the bottom of the page with swizzle before, but couldn't figure out how to get it to show on the right.
At this point I'm probably better off waiting for this configurable breakpoint to get fixed.

[slorber]

If we hide the right TOC on mobile, it's because there's no place left in the mobile layout 🤷‍♂️ 😅 I really wonder where you want to display it exactly.

[neoakris]

I'll repost what I shared on another thread, to save time / not have to re-upload

Docusaurus looks great on phones / there's plenty of room on Mobile View in Landscape mode, even if it was slightly cramped users can just shrink the sidebar.
But virtual pixels convert high pixel density phones to have artificially small viewports, which prevents them from crossing the 996px threshold.
so phones rotated in landscape view, are forced to view in Mobile View.

o right btw I did discover a workaround (but it has to be done per end user device, you can use this to check the official site)

1. chrome mobile
2. chrome's 3 dots --> settings --> accessibility --> show zoom option in main menu
3. visit docusaurus.io/docs
4. chrome's 3 dots --> zoom --> 75% zoom (zoom tweaks the virtual pixels to hit the desktop threshold, the site ends up being very readable in landscape mode, and if someone wants the view you showed they'd just rotate their phone to portrait mode.)