[jira] [Created] (GEODE-7125) Simplify documentation navigation (remove left nav parent links; add in-page TOCs)

["Joey McAllister (Jira)" <ji...@apache.org>]

Joey McAllister created GEODE-7125:
--------------------------------------

             Summary: Simplify documentation navigation (remove left nav parent links; add in-page TOCs)
                 Key: GEODE-7125
                 URL: https://issues.apache.org/jira/browse/GEODE-7125
             Project: Geode
          Issue Type: Improvement
          Components: docs
            Reporter: Joey McAllister


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.

 



--
This message was sent by Atlassian Jira
(v8.3.2#803003)