Sticky sidebar

[tjex]

Resolves #140

Description

Describe the purpose of this PR along with any background information and the impacts of the proposed change. For the benefit of the community, please do not assume prior context.

Provide details that support your chosen implementation, including: breaking changes, alternatives considered, changes to the API, etc.

If the UI is being changed, please provide before/after screenshots.

Sticky sidebars are a great UI functionality, as the user doesn't need to scroll up to access menu / nav items. This PR implements this behaviour idiomatically with the original terminal.css approach and uses global variables for spacing that are already in use within the code base.

This is a draft PR for now as merging in the current state would create a 'breaking change' of sorts to current users. Their sidebars would all become sticky by default.

I'm therefore looking for some feedback as how best to toggle this functionality via theme options, e.g, navigation.side.sticky = true

{%- if "navigation.side.sticky" in features -%} make sticky {%- endif -%}

I tried to create an if - else block in side-panel.html to insert the div elements required for the sticky sidebar. As without div elements, the sidebar will not stick (also a bit of a hacky solution?). Along the lines of this. But I get an error about block side_nav being included twice:

{%- set features = config.theme.features or [] -%}
{%- if "navigation.side.hide" not in features -%}
{%- if "navigation.side.sticky" in features -%}
<div>
<aside id="terminal-mkdocs-side-panel">
    {%- block side_nav %}{% include "partials/side-nav/side-nav.html" %}{%- endblock side_nav %}
    {%- block side_toc %}{% include "partials/side-panel/side-toc.html" %}{%- endblock side_toc %}
</aside>
</div>
{%- else -%}
<aside id="terminal-mkdocs-side-panel">
    {%- block side_nav %}{% include "partials/side-nav/side-nav.html" %}{%- endblock side_nav %}
    {%- block side_toc %}{% include "partials/side-panel/side-toc.html" %}{%- endblock side_toc %}
</aside>
{%- endif -%}
{%- endif -%}

- Unfortunately, my formatter also found a lot of missing semi-colons in `terminal.css`. 
- I didn't realise it made this change when saving and committing... 
- Makes the pr a bit messy. Lines of implementation in `terminal.css` are 407 and 856.

Testing

The theme can be built and served directly: make build-locally-and-serve.

Then select a menu item that shows a page with enough content to scroll, and scroll down the page. Make a narrow screen so the sidebars become top flex boxes, and scroll again (sidebar is static again).

Checklist

• [ ] I have added documentation for new/changed functionality in this PR or in mkdocs-terminal/documentation
• [ ] All active GitHub checks for tests, formatting, and security are passing

[ntno]

hi @tjex ty for the contribution! a sticky sidenav option would be most welcome let me check it out

[ntno]

hi @tjex thank you again for the contribution! i haven't worked on this project in a while but it is inspiring to know folks are using this theme! happy to work with you more on adding this feature.

i picked out just the css and div change just to take a quick look. one thing i noticed is that the "Side Navigation" component takes precedence over the "Table of Contents" component. ie you aren't able to see a page's table of contents until you scroll all the way to the bottom of the page.

for example here is the "Git Revision" plugin page locally:

vs compared to the live site where you can see the full Table of Contents component (at least until you scroll the main page content past it) https://ntno.github.io/mkdocs-terminal/configuration/plugins/git-revision/

idea

what if the side panel containing the navigation and table of contents components scrolled separately from the main page content. when your mouse is hovered over the left-hand side you can scroll to see the full page listing and the TOC. then when you move your mouse over to the main content the left-hand side would stay frozen and scrolling would manipulate the main page content instead. what do you think?

**edit to add: not sure how we would implement this as i don't have a lot of CSS experience one thing to keep in mind is that currently the side panel and main content use this grid layout: https://github.com/ntno/mkdocs-terminal/blob/main/terminal/partials/styles.html#L32

[ntno]

for implementation if we want to add/remove styles based on feature flag we can add a section here: https://github.com/ntno/mkdocs-terminal/blob/main/terminal/partials/styles.html

[tjex]

Thanks for making it :) We'll potentially be going with mkdocs for the documentation of zk. And would like to use this theme if so!

So, great catch about the TOC only effectively becoming usable once we reach the bottom of the screen. I didn't actually notice this because my screen is big enough that the whole nav + toc fits onto it! Perils of good hardware 🤷‍♂️

It is quite a tricky one in a way. My initial reaction would be to put the TOC on the right side anyway, which is a pretty common layout these days for docs and reduces the amount of vertical movement with the eyes / mouse.

But it still wouldn't be a robust solution in general, as perhaps someone out there has a stack of menu items, that already goes out of frame (or they're viewing on a very small screen). Then their own nav menu wouldn't be fully usable until they reach the bottom of the screen.

Hmm. I'm not sure how tricky it is to implement that the side nav is scrollable itself, I'd expect not so bad.

As an interim solution, what are your thoughts on putting the TOC on the right side, and setting them as sticky via a config feature option? Then, if time permits, we could have a look at also making it scrollable, for the cases where the nav menu is that huge / viewing screen is that small?

I'd say for the vast majority of cases, this would suffice? In essence, if someone has a nav bar so full, that it's already exiting the screen, then they would have no use for a scrolling side bar anyway (so they wouldn't even enable it)?

[ntno]

hi @tjex i'd be open to trying adding the TOC on the right hand side we would want to make sure the TOC stays above the main content when the screen is made more narrow (as opposed to under the main content where it wouldn't be useful)

related to this issue: i realized that this MkDocs theme is now a few versions behind the terminal.css upstream. currently we are at v0.7.2 but v0.7.5 is the latest available.

i am going to upgrade to v0.7.5 and see if this resolves the sticky problem without extra work from us. currently testing 0.7.4 here: in PR #143 i decided to skip 0.7.3 since it was released on the same day as 0.7.4 and the diff is empty

[ntno]

v0.7.4 merged testing v0.7.5 here: #150

[ntno]

hi @tjex can you try out this override CSS on your site and let me know what you think?

Sticky Side Panel Override CSS: https://github.com/ntno/mkdocs-terminal/pull/152

MkDocs Extra CSS Feature: https://www.mkdocs.org/user-guide/configuration/#extra_css