Navigation: allow user to hide left and right sidebar

[eschachar]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

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

Add buttons to the mkdocs site so users can hide the sidebars (LHS Index and the RHS Table of Contents) and the content on the page expands to the left and right.

Currently, mkdocs-material supports hiding the sidebars by adding logic to a particular .md file (see here). But that requires a change to the underlying .md file. Instead, it'd be great to have buttons that allow users to hide the LHS index and/or RHS TOC, so that the content on the page extends farther into the margins.

Use Cases

This feature would give users the ability to widen the page of the content they're looking at while retaining their flexibility to bring back the index and TOC sidebars when they're ready to navigate to a new page.

Screenshots / Mockups

For example, here is how it's done through Mode. Once you hide the LHS and RHS sidebars, the space where you do the work expands across in both directions. A user can then easily toggle back and forth with and without the sidebars.

[squidfunk]

This feature suggestion has been open for more than 3 weeks and has received almost no upvotes. I'm currently not considering it for implementation, as I don't think many users will need it. Closing.

[squidfunk]

Re-opening. We're currently re-evaluating this change.

[squidfunk]

Here's a prototype that demonstrates how this could look like:

Ohne.Titel.4.mp4

Each sidebar now has a second part that always snaps to the bottom of the screen. In the future, we could even use those containers to host further navigation items like Print page, Edit this page or other buttons that apply to the document.

Feedback appreciated!

[xsa]

Here's a prototype that demonstrates how this could look like:

Ohne.Titel.4.mp4
Each sidebar now has a second part that always snaps to the bottom of the screen. In the future, we could even use those containers to host further navigation items like Print page, Edit this page or other buttons that apply to the document.

Feedback appreciated!

I like it. any chance we could have a config knob to set whether we'd like to have these buttons at the top or bottom of the page? If the left and right TOC's are sticky, I'd prefer to have the buttons at the top. Thanks!

[squidfunk]

I like it. any chance we could have a config knob to set whether we'd like to have these buttons at the top or bottom of the page? If the left and right TOC's are sticky, I'd prefer to have the buttons at the top. Thanks!

Funnily, I first experimented putting them at the top – it doesn't really work well. We can't put the buttons next to the sidebars, because when the screen size is 1220px - 1240px, they would not be visible anymore. Putting them on to the sidebar title will also not work, as they might overlay it, depending on what you put into the title. The only thing that could work would be to move them above the title of the sidebar, which looks weird. IMHO, putting them at the bottom seems to be the best solution to me, but I keep experimenting. If somebody has a good idea for better mechanics that work with everything that we already have, I'm happy to discuss! In that case, please create some visuals.

[xsa]

I like it. any chance we could have a config knob to set whether we'd like to have these buttons at the top or bottom of the page? If the left and right TOC's are sticky, I'd prefer to have the buttons at the top. Thanks!

Funnily, I first experimented putting them at the top – it doesn't really work well. We can't put the buttons next to the sidebars, because when the screen size is 1220px - 1240px, they would not be visible anymore. Putting them on to the sidebar title will also not work, as they might overlay it, depending on what you put into the title. The only thing that could work would be to move them above the title of the sidebar, which looks weird. IMHO, putting them at the bottom seems to be the best solution to me, but I keep experimenting. If somebody has a good idea for better mechanics that work with everything that we already have, I'm happy to discuss! In that case, please create some visuals.

Thanks for the thorough explanation. In an earlier version of Material, saw someone doing it that way, for the right hand side TOC. See the grey chevron button at the top right of this screenshot. That's what I had in mind, with my previous comment:

[squidfunk]

I personally don't really like that the button has no spacing to the header, and adding padding would push the table of contents further down. I'll continue experimenting, but it looks like the bottom is a better place for additional navigation items, as said before, like printing the current page, or adding further dynamic data.

However, with some CSS, it should definitely be possible to push the button to the top, so maybe we'll gravitate towards the bottom as a default, and provide some extra CSS that allows the author to change positioning. Thanks for your feedback!

[squidfunk]

As another example of a popular framework putting those buttons at the bottom, see https://docusaurus.io/docs:

Additionally, the bottom of the sidebars is very often empty, so I think (but that's obviously an opionion) using that space is better to make it discernable that it's actually possible to collapse the sidebars. It's easier to see, because of empty space:

[xsa]

As another example of a popular framework putting those buttons at the bottom, see https://docusaurus.io/docs:

Additionally, the bottom of the sidebars is very often empty, so I think (but that's obviously an opionion) using that space is better to make it discernable that it's actually possible to collapse the sidebars. It's easier to see, because of empty space:

That sounds logical.

[odysseu]

neat feature, looking forward to using it

[mfridman]

Created a duplicate discussion, #6359, before finding this issue.

I think this would be really nice in the context of a blog, to have a "distraction-free" and minimal reading experience.

I wonder what it'd feel like if it were automatic, and worked like the header.autohide.

As you scroll down the side items disappear and as you scroll up a bit the sidebar bits re-appear. The sizing stays the same, so there's no jitter in the page sizing.

[andreilgeorgescu]

I think this would be really nice in the context of a blog, to have a "distraction-free" and minimal reading experience.

I wonder what it'd feel like if it were automatic, and worked like the header.autohide.

As you scroll down the side items disappear and as you scroll up a bit the sidebar bits re-appear. The sizing stays the same, so there's no jitter in the page sizing.

I agree with the idea of a "distraction-free" mode. On top of using Material for MkDocs for technical documentation, I'm also using it to write an interactive technical book. For a book, the combination of navigation.sections, toc.integrate, header.autohide, and mkdocs-enumerate-headings-plugin make for an enjoyable reading experience.

The only major pain point from what I can tell so far is the lack of ability to hide the sidebars. The options for sidebar toggling and sidebar autohiding would really bring it all together.

[alexvoss]

Another use case is tutorials. Note that we also had requests (most recently #6404) about extending the width of the content. The prototype addresses this as well.

It might be good, though, to give page authors or even users the choice to expand to full screen width or not. Some people may be looking for a distraction free mode but will want to maintain a sensible line-length. To my mind, hiding the navigation elements and expanding the width are orthogonal.

[squidfunk]

This sounds more like a "Zen" mode that you can enter and exit than hiding sidebars independently. I suggest that we move this into a new change request, so we can discuss how this could look.

[NikosAlexandris]

Here's a prototype that demonstrates how this could look like:
Ohne.Titel.4.mp4

Each sidebar now has a second part that always snaps to the bottom of the screen. In the future, we could even use those containers to host further navigation items like Print page, Edit this page or other buttons that apply to the document.

Feedback appreciated!

What is the status of this functionality ?

[squidfunk]

Prototype, we're currently working on other things ☺️

[HonkingGoose]

From @squidfunk a few comments up:

This sounds more like a "Zen" mode that you can enter and exit than hiding sidebars independently. I suggest that we move this into a new change request, so we can discuss how this could look.

I love the "Zen mode", "distraction free mode" or "reader mode" idea. ❤️ I just checked, and I don't see a issue or discussion for this yet. Do you want me to start a new Ideas discussion?

[NikosAlexandris]

I am sure you are aware of "other" design approaches out there, yet just mentioning : https://jupyterbook.org/en/stable/content/figures.html?highlight=margin#margin-captions-and-figures. You can see that the right menu doesn't get on the way of margin content (just scroll up & down a bit).

[squidfunk]

Do you want me to start a new Ideas discussion?

You can do that, but note that the Zen mode is currently not a priority. Might happen at some point, though.

[alexvoss]

You can see that the right menu doesn't get on the way of margin content

Personally, I find the animations too hectic.

[NikosAlexandris]

You can see that the right menu doesn't get on the way of margin content

Personally, I find the animations too hectic.

May be. For what is worth, having some extensive experience in working with Jupyter Book, it feels that the area width, etc. works better to show stuff, like code, etc. without having to scroll horizontally or to put things on the margin or have full width components (inspired by Edward Tufte's creations). I think this is one point where Material is in some sense more restrictive.

[squidfunk]

@NikosAlexandris you can adjust the width with a few lines of CSS to your taste, as explained in our documentation:

.md-grid {
  max-width: 1440px; 
}

[NikosAlexandris]

@NikosAlexandris you can adjust the width with a few lines of CSS to your taste, as explained in our documentation:

.md-grid {
  max-width: 1440px; 
}

Thank you, I have that already. It's some maximum that will play or may not play a role depending on the screen size etc. This does not give flexibility to adjust the width of the content (for various components, independently of the page width) we can show in a page, though. It's a global property anyway.

[squidfunk]

You can set it per template, which you can set per page, or just drop some CSS in a page, if you just want to set it for one page, like so (add to Markdown):

<style>
  .md-grid {
    max-width: 1440px; 
  }
</style>

# Page headline

...

Regarding components: no you cannot adjust the width of a component to exceed the page width easily, but this is something that has to be given a lot of thought, so it works on all screen sizes. We try to make things as simple as possible and this comes with some caveats, but we try to keep those to a minimum and allow for maximum flexibility. The hiding of the table of contents as shown in your example is currently not supported, and not planned, because I believe it has a very small upside compared to its implementation complexity and gain (only really pays off on big screens).

[NikosAlexandris]

You can set it per template, which you can set per page, or just drop some CSS in a page, if you just want to set it for one page, like so (add to Markdown):

<style>
  .md-grid {
    max-width: 1440px; 
  }
</style>

# Page headline

...

Thank you, I was not aware of this and it is useful.

Regarding components: no you cannot adjust the width of a component to exceed the page width easily, but this is something that has to be given a lot of thought, so it works on all screen sizes. We try to make things as simple as possible and this comes with some caveats, but we try to keep those to a minimum and allow for maximum flexibility. The hiding of the table of contents as shown in your example is currently not supported, and not planned, because I believe it has a very small upside compared to its implementation complexity and gain (only really pays off on big screens).

Of course, I understand. For my use-case, I am concerned on how to show nicely output from the command line, i.e. using markdown-exec. The output of code blocks is often truncated (i.e. Tables formatted with the rich library won't show nicely as they do print out in a regular terminal). A full width block would certainly solve this problem. Surprisingly, putting the code block inside an admonition, decreases the font size but keeps the output intact, i.e. no truncated content, column names, etc. I'd be nice to have some transparent admonition or so to ab-use it in such cases (?!) :-).

By the way, all examples at markdown-exec/gallery are shown on a page with a hidden navigation (left) sidebar and I think not without a reason. But, how do you get then the navigation accessible if this page is part of many pages under the same top-section ? There is

  features:
    - toc.integrate 

and I use it. But it may feel saturated in a context of many pages. The separate ToC improves legibility in my humble view.
This is just one example but I guess there are many such how-to-questions to answer out there.