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)
