Documentation: Persistent sidebar nav and/or overview #19476
Description
Verification
- This issue's title and/or description do not reference a single formula e.g.
brew install wget. If they do, open an issue at https://github.com/Homebrew/homebrew-core/issues/new/choose instead.
Provide a detailed description of the proposed feature
As discussed in this comment, I believe a persistent (always visible) sidebar nav (showing the various documentation pages) and/or overview (high-level, hierarchical view of current page) would be useful.
What is the motivation for the feature?
Some tasks, such as adding a new cask, have multiple relevant pages to track, e.g.:
- https://docs.brew.sh/Adding-Software-to-Homebrew
- https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request
- https://docs.brew.sh/Cask-Cookbook
- https://docs.brew.sh/Acceptable-Casks
Having a persistent nav would help keep track of where you are in the overall structure of the documentation, and help learn and retain a mental model of that structure, including which pages contain what info.
Further (and more importantly, IMO), a persistent overview of the current page would allow one to better understand the structure of the page and their current position within it, and navigate between sections without having to move back and forth to/from the top of the page. (A very long page like the cask cookbook feels like a wall of text without it, and the lack of extra whitespace between sections exacerbates this).
Without these features, I found myself forgetting which page I had seen a relevant section on, and doing a lot of scrolling and switching between tabs to find it. My brain was quickly overloaded by the process.
How will the feature be relevant to at least 90% of Homebrew users?
It will be relevant to all users of the documentation, particularly those who are new to it.
What alternatives to the feature have been considered?
None