Icons in the menus

[narrenfrei]

I'm working on some updates improvements around our menus. #342 #449 #450
In #342 was asked about adding icons to the menu items. So I took a look, if there already exists a official possibility in Hugo and/or Docsy.

In the examples of the Hugo docs (https://gohugo.io/content-management/menus/#add-non-content-entries-to-a-menu) they are using the parameter pre of the menu entries for adding icons. But in Docsy the parameter pre (and post) is not supported.

My suggestion:

• Add support for pre and post for menu entries threw config.toml, to support this "official" feature in the hugo docs.
• Introduce in Docsy a new meta data (front matter) term (maybe called icon) to define an icon at page level directly in the content files. In this parameter a icon could get defined by the common Font Awsome classes (eg. "fa fa-road").
  • This new parameter ´icon` could get used to show icons in the side bar tree menu.
  • And I would also make a possibility to set icons to the main menu also in this way (with the common Font Awsome classes). Because the HTML markup (and default formatting in CSS) is better definable, when only the classes are allowed than a injection of any code threw pre/post parameter.

This approach would also solve #444

Any comments?

[narrenfrei]

As it's not possible (or not so easy) to define a new entry for the menu properties (https://gohugo.io/variables/menus/), I think it's better to use ONLY the parameter pre for icons in the main menu, as already suggested in the official Hugo docs. And use my suggested front matter parameter icononly for the side bar tree menu (and the section-index.html).

[narrenfrei]

First version is online:

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

[Symbolics]

I like it. You are doing wonderful work, and clearly have some talent/skills as a web designer.

My only comment, as a user, is that both the triangle and icon may not be needed at the top level. Perhaps use the icon to expand the section at the top, and the triangle for 2nd and 3rd level expansions.

[narrenfrei]

I'm also not really happy with how it looks when using icons AND the toggle buttons for folding. This is due to the fact that the theme should remain as flexible as possible:

Maybe someone want's a foldable menu, but doesn't want to use icons. What happens, when icons are only defined for some menu items?

And the most important reason for using the toggle buttons for folding as they are: How can the user recognize, that a menu item can get unfold? The fact, that a menu item with siblings has also his own page, make it necessary, that there are to regions with links for each menu item with siblings: (1) to fold and unfold the subitems and (2) to open the parent page.

https://istio.io/latest/docs/ have solved it in that way: They don't link directly to the parent page in the menu and have no specific content in pages on the 1st level. But in Docsy you can't say, that this is correct for all users out there.

Maybe with a optional parameter in the meta date of each page (eg folder-icon) I could make it possible to overwrite the current toggle buttons. But what would be the right animation to give a hint for the user, that there is the fold/unfold function hidden in these icons?

[LisaFC]

I like the functionality very much but I agree, I think the toggles and the icons together look cluttered. You'd need to do a fairly serious revamp on the menu presentation for the icons to make visual sense, I think? Icons might work better on a docs landing page with cards (like k8s), if not a heavily customized menu.

The Istio look and feel is nice but it's very specific to that site and how it's structured/looks (I worked on the project, though not as a designer!), which is why I'd be wary of trying to pull too much of it into a general purpose template that shouldn't impose too much "distinctiveness".

For the toggles, let me have a look around some sites and see if I can see a nice light visual cue for "this is expandable"....

[LisaFC]

I do quite like the icons in the top nav, btw! Though I think this should be something users can toggle as it may not fit with the look they're going for in their site (and obvs they may want to add their own custom icons).

[narrenfrei]

All icons can be changed by the user. In the "default" setting from Docsy there would be no icons at all.

The icons on the main top menu have to be defined per menu item in the config.toml (or in the parameters for the main menu directly in the content files) as it's described in the Hugo docs.

The icons for the sidebar menu have to be defined by the user in an icon parameter in the content file. If not, no icon is shown dir this menu item.

[LisaFC]

We now have the option to have icons in both menus (hurrah!), so can we safely close this?

[narrenfrei]

Yes, I close it.