Toggle expand/collapse for left-side menus/TOC

[prdsoftware]

Firstly, love the theme - thanks for the hard work that's gone into this.

Is it possible to expand/collapse the menu structure on the left?

While I'm at it, is it possible to reduce the font-size a point or 2 for the left-menu structure. Many titles are wrapping over 2 lines, but with a font size slightly smaller, this wouldn't happen - at least for the words I'm using - is this a CSS thing?

[gwatts]

@prdsoftware to change whether the left menu is expanded/compact, in config.toml you can set the sidebar_menu_compact parameter (see https://www.docsy.dev/docs/adding-content/navigation/#section-menu ):

 [params.ui]
# Enable to show the side bar menu in its compact state.
sidebar_menu_compact = false

You can also control what appears in that left-menu on a per page basis, so you can choose a shorter title that fits better there by setting linkTitle in the page matter at the top of each page (see also https://www.docsy.dev/docs/adding-content/navigation/ )

---
title: "My nice long page title"
linkTitle: "Short title"
weight: 10
---

If you want to make the font size smaller for that nav, try this in your project's assets/sccs/_variables_project.scss file (see also https://www.docsy.dev/docs/adding-content/lookandfeel/)

.td-sidebar-nav {
  font-size: 0.8em !important;
}

(there might be a better way of overriding that css; it's not my strong suit ;-) )

[prdsoftware]

Thanks @gwatts. I was referring to the ability to manually toggle the collapse/expand state. Have a +/- button so that the user can toggle it as they wish. Is there a setting for this?

I'm also aware of the linktitle, but I'll fiddle around with the CSS. I find the font size just a touch too big by default.

[gwatts]

understood - afaik Docsy doesn’t have any facility for dynamically expanding that tree at the current time hopefully the SCSS snippet is useful (tester working for me)

…

Sent from my Psion 3c

On Sep 27, 2020, at 22:11, prdsoftware ***@***.***> wrote:  Thanks @gwatts. I was referring to the ability to manually toggle the collapse/expand state. Have a +/- button so that the user can toggle it as they wish. Is there a setting for this? I'm also aware of the linktitle, but I'll fiddle around with the CSS. I find the font size just a touch too big by default. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[prdsoftware]

@gwatts Thanks for the CSS - works great! Just what I was after.

Hopefully the dynamic TOC expansion will make it in one day. For a documentation theme, this seems like a must-have feature.

Thanks again.

[quickstar]

Hi agree
For me it's a must-have as well! I would highly appreciate such a feature!

[prdsoftware]

The support team at Netlify have kindly given some advice on this issue that may be helpful. When you click on a menu that has sub-items / children, Docsy displays a section listing in the main panel, and expands the parent node in the menu. Their advice was you can't have both - eg. You can have a menu toggle as well as a section preview/listing of sub items.

Is there a way around this?

They gave this snippet of CSS that does display a "+" after the menu though. Update assets/scss/main.scss

li.td-sidebar-nav__section-title a:after { content: ' +'; // customise it as per needed or use a SVG, etc. }

It's just a visual indicator that there are child objects. The default styling is too subtle to my liking.

Would love to see a proper toggle of expand/collapse that also maintains the section preview listing.

[Mrt134]

Adding a +1 for expand/collapse.

[Symbolics]

Let me add a vote for this. My navigation bar is getting quite long now, and this feature is the one thing that folks I've showed the Docsy site comment on. All the Python/RST/Sphinx docs have got this and it really help browsing the TOC.

[prdsoftware]

If your navigation/TOC is getting long, you should also be getting this by now. #348

Hopefully both issues can be fixed by someone in the know... ;-)

[Symbolics]

I had a quick search on this topic, and there seems to be several tutorials on the topic of an expandable table of contents. A few that look interesting, with HTML, CSS and JavaScript:

https://jsfiddle.net/qszpx1v7/188/
https://jsfiddle.net/Vd5BH/5/
https://stackoverflow.com/questions/51942158/expandable-table-of-contents-with-buttons
http://mleibman.github.io/SlickGrid/examples/example5-collapsing.html
https://stackoverflow.com/questions/5636375/how-to-create-a-collapsing-tree-table-in-html-css-js

Hopefully there's something in there that a knowledgeable person could pinch for this. Or perhaps the best route is to use whatever it is Sphinx uses.

[Symbolics]

Are we able to take styling from other Hugo sites? For example, the Doks theme, has a nicely formatted TOC that, whilst not expandable, does nicely organize the content. I like the separators and bold headings. This may be a good interim solution

[Symbolics]

Adding a bit more information. Whilst browsing other documentation themes, I notice that Docdocks and Learn have nearly identical TOC navigation:

This makes me think that there must be a TOC module somewhere that they are both using. Unfortunately neither mention what it is in their own documentation, but the Docport description of menu customization and Ace documentation are all so similar to one another I am beginning to suspect it could be built into Hugo (?).

[narrenfrei]

There are quite a lot of tutorials using JS. I fount also a pure CSS version:
https://code-boxx.com/css-collapsible-tree-menu/

What's your opinion - JS or pure CSS?

[snunez1]

I am not an expert on web front ends, but I believe from my reading that CSS solutions are generally preferred these days.

[narrenfrei]

Here is my first (pure CSS) trial:
https://narrenfrei.github.io/docsy-dev-page/docs/

In the config.toml you can switch between the foldable side bar menu and the "normal" one by setting sidebar_menu_foldable = true.
With the parameter sidebar_menu_unfold_depth you can set, how many levels you want to display unfolded. The current path is always unfolded.

Here is the code:
https://github.com/narrenfrei/docsy-dev-page/tree/foldable-sidebar-menu

[Symbolics]

Looks nice. Big improvement over what's there now.

Can the colour of the expansion arrows be changed?

[narrenfrei]

Looks nice. Big improvement over what's there now.

Can the colour of the expansion arrows be changed?

Yes, of course. When we have a final version, I'll make separate SCSS file with comments.

[Symbolics]

Nice! Images too? See istio for an example: https://istio.io/latest/docs/

[prdsoftware]

Great work. Looking forward to this improvement. Thanks for your hard work on this.

[narrenfrei]

Nice! Images too? See istio for an example: https://istio.io/latest/docs/

I'll also working on an approach to define icons for each menu item: #457
But I'm not sure, if it will look so good in combination with the button to open and close the menu levels.

[narrenfrei]

New Version is online.

https://narrenfrei.github.io/docsy-dev-page/docs/

[LisaFC]

As I said on the other thread, expand/collapse functionality looks great! Would a lighter/smaller caret symbol be a less "heavy" or distracting cue that the sections are collapsible? https://fontawesome.com/icons/caret-right?style=solid

It's what we use in Google Cloud for example: https://cloud.google.com/anthos/multicluster-management?hl=en

[narrenfrei]

I've changed the icon for fold/unfold the menu icons to your suggestion and I think, that it would be good compromise between using my foldable menu with or without defining additional icons for the menu items.

As I explaned at #457 (comment): All icons for menu entries (main menu and side bar menu) have to be defined by the user for each menu entry resp. page. If there is no icon defined, no icon will be shown. So the menus work out of the box like before.

In the config.toml the user can choose between the normal menu or the foldable and can additional set the depth of unfolding the menu:

sidebar_menu_foldable = true
sidebar_menu_unfold_depth = 1

At the moment I'm tweaking the "old" menu without folding to show menu icons if defined.

[LisaFC]

Excellent, the carets work well! Maybe in a dark grey or the theme blue (main color) so that the text pops a bit more? I like the configurable aspect too. This is really great work, thanks!

I think I possibly just don't like icons in the TOC in its current style, I find they make the text less scannable, but if other users want them....

[narrenfrei]

Oh, now we're getting picky. ;-) No, thanks for the feedback. Yes, I think with black they are a little bit too eye catchy. A dark gray could make it better.

I also don't really need icons in the side bar menu - especially in docs and in combination with a foldable menu. But I thought, when I take the whole thing (menu structure, foldable menu, ..) in hand, I could also integrate a possibility to define icons.

[narrenfrei]

@LisaFC What is better to handle for you, one PR with all my adaptions or separate PRs for each topic?

[LisaFC]

Separate PRs might be easier in terms of resolving issues etc. - as long as if there are any dependencies we merge them in in the right order.

[nryberg]

Really like where this is going - looking forward to implementing these changes!

[jcrd]

I think this issue can be closed as it was addressed in PR #518.

[deining]

Expand/collapse fucnctionality can now be enabled for left-side menu.
Closing this ticket.