Details
-
Improvement
-
Status: Closed
-
Minor
-
Resolution: Won't Fix
-
None
-
None
-
None
Description
The Geode user guide uses Bookbinder to create HTML documentation from markdown files. This ticket is about changing two ways in which Geode currently uses Bookbinder sub-optimally:
- For listings in the left navigation with submenus, we give the parent listing a link to a TOC page—e.g., [Prerequisites and Installation Instructions|https://geode.apache.org/docs/guide/19/prereq_and_install.html]. This isn't inherently bad (though it is somewhat redundant, as the left navigation also serves this purpose), but when a user visits such a link, the submenu on the left collapses. Note: The menu does not collapse when a user visits a child link in the submenu of these items.
- Fix/Improvement: Wherever possible, remove the link from the subnav parent item (leaving the now-unclickable parent item) and the related TOC page. If the TOC page contains content beyond a TOC for the child pages, move that content to an appropriate place within the existing child pages or, if necessary, create a new page for it. For instance, the information above the TOC in [Configuring and Running a Cluster|https://geode.apache.org/docs/guide/19/configuring/chapter_overview.html] could move to a new page at the top of that parent's submenu or, more likely, to the Overview of the [Cluster Configuration Service|https://geode.apache.org/docs/guide/19/configuring/cluster_config/gfsh_persist.html] page.
- For left nav listings with submenus where all the pages link to anchors within a page (instead of to topics on individual pages), Bookbinder provides an option called "quicklinks" that automatically uses H2 (`##`) and smaller subheads to create a small, in-page TOC at the top of the page. We currently disable this functionality.
- Fix/Improvement: Remove the "no-quicklinks" tags from anchors that we want to appear in the in-page TOC. Also remove any duplicate links from the left navigation. (In other words, the in-page TOC will now replace some navigation functionality currently performed by the left nav, thereby simplifying the left nav.) For example, see [Managing Heap and Off-heap Memory|https://geode.apache.org/docs/guide/19/managing/heap_use/heap_management.html], where many (but, notably, not all) of the child links in the left nav lead to anchors within one page. These can become one new child page/link called Managing Heap Memory, leaving only Resource Manager Example Configurations, Managing Off-Heap Memory, and Locking Memory as child links alongside the new one. The rest become in-page TOC anchor links in Managing Heap Memory.