[
https://issues.apache.org/jira/browse/GEODE-7125?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Dave Barnes closed GEODE-7125.
------------------------------
> 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
> Assignee: Dave Barnes
> Priority: Minor
>
> 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.20.7#820007)
