[V2] Change mobile theme button behavior to enable page heading TOC

markerikson commented 4 years ago

🚀 Feature

The Docusaurus v2 mobile theme does not currently implement a way to view the in-page headings TOC that appears in the right sidebar in the desktop theme.

I propose altering the v2 mobile button behavior to consolidate all page nav link access from the upper-left hamburger button, and convert the lower-right floating button to showing the page headings TOC instead.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

There are three major navigation sections in a standard Docusaurus page:

The top nav bar shows a short list of major links, like "Docs", "Tutorials", "Github", etc, and includes the search input
The left sidebar contains all the actual docs page links, grouped into collapsible categories
The right sidebar shows the H2/H3 headings for the current page, facilitating navigation within a single page

v1 Mobile Theme

In DSv1, the mobile theme implemented all three nav areas in basically the same way, as seen in this React-Redux docs screenshot:

DS v1 - multiple toolbars

The top nav bar is always visible here, but due to space constraints the nav links are on a second row below the site title + search bar.

In addition, there's a third top toolbar, containing the current page title and two more buttons. The upper-left out-arrows button triggers showing the left sidebar:

DS v1 - left sidebar

While the upper-right hamburger button shows the current page headings TOC:

DS v1 - right sidebar

The flaw in this design is that the multiple top toolbars take up a lot of extra space.

v2 Mobile Theme

DS v2's mobile simplifies things considerably. There's now just a single top toolbar with the site title and search button, as well as a hamburger button in the upper-left. There's also a floating button in the bottom right:

DS v2 - whole page

The upper-left button now shows the content from the top nav bar links, in a pop-over layer that shows the links stacked vertically:

DS v2 - top nav bar

The bottom-right button shows the content from the left sidebar:

DS v2 - left sidebar

v2 Theme Observations

The v2 theme top bar behavior is a major improvement over v1, because there's only one top bar visible at all times. That saves a lot of vertical space.

However, the v2 theme has no way to show the page TOC. This is a major deficiency compared to v1.

Pitch

I would specifically like to see the v2 mobile theme rewritten so that:

The upper-left hamburger button shows a popup layer that contains both the top nav bar links and the left sidebar categories + pages TOC. I imagine that the links from the top nav might be added as an extra pseudo-category on top of the others, perhaps labeled "Nav Links".
The lower-right floating button should be changed to show a popup layer that contains the in-page headings TOC from the right sidebar.

This would be a distinct improvement, because:

All page navigation UI is now triggered from the same button, in the upper-left
The page heading TOC is now accessible, when before it wasn't

phryneas commented 4 years ago

This is really problematic, as for someone with a 50%/50% screen split, finding certain navigation points becomes really non-intuitive.

markerikson commented 4 years ago

@yangshun , @lex111 : any thoughts on this? Seems like it might relate a bit to #2269 .

yangshun commented 4 years ago

This will involve a huge Docusaurus v2 theme change if we want to change this in core. Not opposed to it, but the problem now is that the docs feature doesn't really have access to the mobile menu.

This is not really related to #2269 which is about the navbar.

markerikson commented 4 years ago

Yeah, I know it's a big change to the theme, but that's kinda my point - the theme atm is a significant regression in functionality from v1.

yangshun commented 4 years ago

I kinda like how Next.js does it.

nextjs org_docs_getting-started(iPhone 6_7_8 Plus)

nextjs org_docs_getting-started(iPhone 6_7_8 Plus) (1)

I suggest the following changes:

An item fixed at the top for the sidebar contents, similar to Next.js mobile docs. Clicking on it shows the full screen page of sidebar docs, same as what we have now
The current hamburger at the bottom right shows a full screen page for table of contents

markerikson commented 4 years ago

Yep, that sounds good to me!

markerikson commented 4 years ago

As an added reference item, Jared Palmer just specifically pointed to the DSv2 mobile theme as one of the reasons why he went with Next.js instead of DS for the new Formik docs:

https://formik.org/blog/new-docs#why-not-docusaurus-v2

slorber commented 4 years ago

Yes, seen this too and agree that current mobile nav is awkward.

This will involve a huge Docusaurus v2 theme change if we want to change this in core. Not opposed to it, but the problem now is that the docs feature doesn't really have access to the mobile menu.

This PR adds the "global data" concept, so it will be more easy to implement this feature, as the main theme layout will be able to access data provided by the docs plugin more easily

https://github.com/facebook/docusaurus/pull/2971

I'm not so fan of the NextJS idea. If it's now possible to put docs details in sidebar, I think having the docs sidebar in the existing mobile sidebar would be better and also takes less space.

Suggestion 1: each version could become a collapsible (sorry for my design skills :p):

Suggestion 2: fold the Docs section, and add the sidebar at the end

michaelknowles commented 4 years ago

In that last design are you still thinking you want to keep the hamburger icon in the bottom right?

The bonus of using a design like NextJS's is that it's then trivial to add the back to top button. We could just add it as pictured below (the red circle) without having to share that space with any other UI components.

slorber commented 3 years ago

As a temporary workaround, for mobile you could embed a TOC directly in your page: https://v2.docusaurus.io/docs/markdown-features/#inline-table-of-contents

This was added recently for the Jest v1-v2 migration, as this feature existed in v1. If you feel it's duplicate to have the 2 tocs for large screens, you can add a class/mediaquery to hide it.

(we'll still try to find a better solution, it's just a suggested workaround)

lex111 commented 3 years ago

What if in mobile navbar just render content from the doc sidebar (without other doc versions, if any)? Something like this:

As a hint, we can display docs version to the right of "Docs":

Now we have opportunity to do this (I mean via hook with global data), right?

markerikson commented 3 years ago

That'd be a good first half :) The other half is making the in-page TOC available again, presumably via the bottom right floating button.

lex111 commented 3 years ago

Hmm, maybe we can modify the local TOC like this: (this is a quick prototype so don't mind the UI).

ezgif com-gif-maker (18)

Accordingly, the lower-right floating button turns into a lower-right back to top button. How do you like this option?

markerikson commented 3 years ago

Looks fine to me! :+1:

markerikson commented 3 years ago

Could we get this prototype polished and added to the next release? I'd love to use it in the Redux docs, right now.

lex111 commented 3 years ago

As I understand new release is very soon, especially since in global data hook missed necessary data (sidebar), so I'm not sure that we can deliver this feature by the next release. cc @slorber

slorber commented 3 years ago

A new mobile UX is available on this PR: https://github.com/facebook/docusaurus/pull/4273

It is ready for a final review here: https://deploy-preview-4273--docusaurus-2.netlify.app/

Please let us know if you find any problem.

Unless bugs are reported, this should be merged soon and be in canary / next release asap.

Notes on design:

We added the mobile TOC accessible at the top of docs, as a collapsible dropdown
a "back to top" button will be added (https://github.com/facebook/docusaurus/pull/4912) and make it easy to scroll back to the TOC
adding an extra/optional floating TOC UX remains a possibility that may be implemented in another upcoming PR

slorber commented 3 years ago

Collapsible mobile TOC:

New "mobile navbar sidebar", that we'll also use in a similar way for other parts (blog post list etc):

slorber commented 3 years ago

This has been merged and will be in beta.4

Please test this on your sites with https://docusaurus.io/community/canary

markerikson commented 3 years ago

Just updated all Redux org docs sites to use beta.4, and it's looking great - thanks for adding this!

facebook / docusaurus