Automatically position the left navigation to the current page

[walkccc]

• I've read the contribution guidelines and agree with them

I want to suggest an idea and checked that ...

• ... to my best knowledge, my idea wouldn't break something for other users
• ... the documentation does not mention anything about my idea
• ... there are no open or closed issues that are related to my idea

Description

Hi @squidfunk, thanks for providing this beautiful theme.
I have an idea. Is it possible to position the left navigation to the current page?

Use Cases

If we have over 1,000 pages, then for example, if we click on page 500, since it's not initially on the left nav (due to the height of the screen), after the rendering, we still can not see where we are in the left nav, and we have to scroll the scrollbar manually.

Maybe allowing the left navigation to automatically "position" with the current page is a good idea. No matter it's a click or by the search.

Screenshots / Mockups

For example, when I click "1391. Check if There is a Valid Path in a Grid" page, the website will look like the following. In this way, I have no idea "where I am."

However, I hope it look something like this:

Thank you.

[squidfunk]

Thanks for suggesting. This was already proposed in #1271 and #1567, but there wasn't much feedback besides the OPs, so it seems that it's not really needed by many users. Let's see if this issue gets some upvotes 😊

[weitzman]

Same issue at https://www.drush.org/commands/10.x/watchdog_show/. I've added my thumbs-up reaction to the initial post.

[squidfunk]

Turns out this is pretty tricky to get right. The naive solution would be to use Element.scrollIntoView, but that yields inconsistent behavior across browsers and sometimes will re-position the entire page, which is very undesirable. I'm investigating other possibilities.

[squidfunk]

Here's a working prototype for the table of contents, which will even follow when the user keeps on scrolling: https://twitter.com/squidfunk/status/1344249178168418304

I think we should solve this for both sidebars and allow to enable this functionality with two new feature flags.

[weitzman]

Looks great.

• This works for the initial page view, or it only kicks in after a scroll? Initial page view is preferable.
• I agree that both sidebars are ideal.

[squidfunk]

The idea is that the active entry is always visible, which also includes the initial load.

[AltarBeastiful]

Looks great ! I believe only on initial page view will already solve many docs where the left menu is long, and we want to read the articles in a sequence. Is there a branch where you started work on this ?

For reference, readthedocs solves that perfectly by scrolling the menu entry selected on top of the page :

For comparison, when going through the articles of the FastAPI documentation, I'm having to scroll the menu each time to reach the next article :

[squidfunk]

Is there a branch where you started work on this?

Not yet! However, given the popularity of this feature request, I'll tackle it as one of the next things to implement.

[squidfunk]

I've added experimental support for positioning correction in Insiders. I'm still figuring out how to generalize this for the table of contents and mobile view (as we have multiple layered panes on mobile), but when you browse the Insiders documentation and reduce the height of the window (the lists are not that long), the positioning is automatically corrected.

Just stepping through the pages by pressing n (= next page) on the keyboard yields:

Ohne.Titel.mp4

EDIT: it also already integrates with instant loading.

[squidfunk]

I'm closing this issue, as Insiders will automatically position the navigation as originally proposed 😊 This was not a dedicated feature but a "silent" improvement. I'm revisiting the positioning later when I address the table of contents.

[alkisg]

When can we expect this feature in the open version?
I don't see it in the funding roadmap...

[squidfunk]

The reason it's not on the roadmap is it's still in prototype stage. I need to generalize the code to also apply to the table of contents. Since there were essentially no reactions on my last two comments, I've concluded that it isn't a priority.

[alkisg]

Well personally I thought that since this issue was closed, it means it was already fixed, and it was only a matter of time to see it in the open version.

Do you need more input? If so, I would suggest that you reopen it, so that people know that the effort is ongoing...
(my experience from open source so far says that for every user that comments in an issue, there are 100-1000 more that are affected and don't even know how to locate the relevant issue, in order to even just press an upvote button...)

[squidfunk]

Sure, we can reopen it until I manage to wrap this up with the table of contents and assign it to a funding goal.

Do you need more input?

Well, at least some feedback would be great, yes. Fixing this issue, nobody left any feedback in nearly 3 months, which I read as no real interest from users. For this reason, I closed it, but I agree that it's good to put a label on when this will be released for general availability. As I wrote before, since there was no interest, I've considered it a prototype that is not ready for release. I always try to maximize the user impact of my time invested.

[kgidarakos]

I'd like to see this feature too.
Thanks in advance

[squidfunk]

@kgidarakos it's already available in Insiders – it's just not ready for official release. If you check out the documentation and make the page narrower so that the menu will overflow, you can see it in action. Screenrecording in #2155 (comment).

[kgidarakos]

I believe that this feature is basic and by definition on all websites! I hope you integrate it in the open version!
Thank you in advance

[usulpt]

this is actually one of the reasons I've decided to hold off on migrating our docs structure to your solution, because it's almost perfect except for this issue. our structure is long and nested and I can't have our users scroll to the location every time they load a page, so if you ever needed feedback to boost it back to life, here it is: wonderful and sorely needed :)

[squidfunk]

Again, this feature is already available as part of Insiders as of today. I just need to find some time to wrap it up, so the table of contents does also exhibit the same behavior. It's just in need of some refactoring.

I just updated the funding goals in 3b1ee9f and linked this feature to the Scotch Bonnet funding goal.

[squidfunk]

Insiders 4.8.0 was just released, adding two new features:

Sidebars automatically scroll to active item

As mentioned in this comment, this was already working before, but not polished to a degree where I thought it was worth releasing/announcing. I polished the source in the latest Insiders release so that it reliably works for the navigation, as well as the table of contents. When you visit a page, the sidebar is automatically positioned to the currently active item.

Here's a narrow screenshot for demonstration, illustrating that active items in both sidebars are scrolled into view:

Try it (narrow your window)

Anchor following table of contents

There's a new feature flag called toc.follow that enables anchor following for the table of contents. When the user scrolls, or jumps to another section of the site after the initial load, the active anchor in the table of contents is scrolled into view:

Ohne.Titel.mp4

Try it (scroll up and down)

This resolves all problems stated in this issue, as now, the active items in both sidebars are always visible. I've assigned the new auto-following feature to the same funding goal as the general sidebar centering – Scotch Bonnet 😊

[pras-ram]

Hi! How do I get this reflected in my current code? I updated to the latest version of MkDocs.

[squidfunk]

@pras-ram This feature is currently only available through the Insiders build. If you want to use it right now, you're invited to become a sponsor and enroll in the Insiders program. You'll be granted access to the private repository in minutes and can use all Insiders features. Otherwise, you'd have to wait until the funding goal is hit.

[wilhelmer]

@squidfunk There are strange things going on with the "Sidebars automatically scroll to active item" feature. In previous versions of our documentation, it worked in all browsers. Now, it only works in Chrome, but not in Firefox. I don't know which version caused the change, it's difficult to track down.

Can you confim it's not working in FF 97?

[squidfunk]

Yes, I can confirm that it doesn't work in Firefox anymore. Please create a new issue, I'll look into it asap.

[SteniMariyaThomas]

This is working in mkdocs-material version 8.5.0 (https://squidfunk.github.io/mkdocs-material/changelog/#8.5.0)

But not working in latest version of mkdocs-material (9.4.4)

[squidfunk]

@SteniMariyaThomas thanks, I looked into it any you're right. This is a regression triggered by the new animated sidebars.

Fixed in 5824c6c.

[SteniMariyaThomas]

@SteniMariyaThomas thanks, I looked into it any you're right. This is a regression triggered by the new animated sidebars.

Fixed in 5824c6c.

Thank you