docs: menu fixes - Githubissues

Way back in #865, it seems the sidebar was customized to be driven by data in config.toml instead of by front matter from content. As I understand it, this was done, at least in part, in order to take control of the order of items in the menu, which until then were in lexical order by title. (Although I think there may have been a simpler resolution available than a custom menu. There is a ordersectionsby = "weight" option that could have been specified in config.toml.)

Per the docs/readme.md our workaround left us in a less than optimal place:

Currently, the weights configured in the config.toml file specify ordering of each section in the main sidebar menu.

Weight values on individual documents are meant to specify ordering of pagination (previous and next navigation) within each doc's section.

This is fairly unwieldy, so if any docs/Hugo pros have knowledge on how to simplify, we'd love the contribution!

In the course of investigating options for internationalizing our docs (see #1828), I've come to believe that a sidebar menu that is driven by data in config.toml instead of by front matter from content is going to be an impediment to internationalization, so I set out to correct this duplication of weights.

This led me to the following:

Undo menu customizations from #865
Remove index from config.toml
Ensure sidebar is sorted by weight using ordersectionsby = "weight" option in config.toml

This left me in a place where the sidebar looked exactly as it should except that in some places the name of the link in the sidebar menu used to be overridden by data that has since been removed from config.toml.

Some research revealed the existence of the predefined linkTitle front matter variable. So I:

Added linkTitle to front matter in our content, as needed.
Minimally customized the sidebar menu to use {{ .LinkTitle }} where it previously used {{ .Title }}.
1. I also discovered that overrides / customizations to Hugo theme are meant to be applied by making modifications in one's own layout/ folder rather than directly overwriting files in the theme's layout/ folder, so I used this approach. See here for reference.

Where this leaves us is:

Menus now are identical to before this PR, but...
We no longer need the duplicate index/weights in config.toml, clearing the path to internationalization.
Our sidebar overrides are a bit cleaner.

brigadecore / brigade

docs: menu fixes #1841