devportal icon indicating copy to clipboard operation
devportal copied to clipboard

Improve the titles in the `_toc.yml` file (navigation sidebar)

Open TibsAtWork opened this issue 2 years ago • 1 comments

The problem

The _toc.yml file is used to generate the navigation sidebar.

Some of the page titles in the _toc.yml file are specified explicitly in the file, some default to using the (top level) heading of the page itself.

Some of those default titles are quite long, and they may contain words that are not needed in the context of the sidebar (for instance, it may be clear what the product is from the tree structure, but the page heading will want to be explicit).

Also, adding ® marks to many top level titles adds visual clutter to the sidebar. We would rather keep the sidebar simple to read.

The solution

It is probably sensible to just specify page titles explicitly in the _toc.yml file for all pages.

It is definitely needed for longer titles, or titles that contain ® or other marks.

Also, add a section on "creating a new page" to the CONTRIBUTING guide, and explain what needs doing to keep the _toc.yml file up to date.

TibsAtWork avatar Mar 18 '22 10:03 TibsAtWork

See also https://github.com/aiven/devportal/issues/580 which is partially related (Improve the heading text when searching for articles. E.g. adding the service name instead of "Aiven Developer documentation") and also https://github.com/aiven/devportal/issues/652 (Improve the titles in the _toc.yml file (navigation sidebar))

TibsAtWork avatar Apr 04 '22 13:04 TibsAtWork