da335975e0d5712f47ee0d19b0eb5003d1a1b7f0
lrnassar
  Mon Apr 27 14:16:44 2026 -0700
Add sticky sidebar table of contents to /docs/ pages, ReadTheDocs-style. refs #36894

staticPage.lua: wrap doc body in a Bootstrap row with a col-md-2 sidebar
holding a .docs-toc nav list and a col-md-10 content column. Collect both
lev==1 and lev==2 headings into the TOC and emit id attributes on <h2>
elements (replacing the prior inline <a name=> anchors).

staticPage.html: add a small vanilla-JS scroll-spy that toggles .active
on the TOC <li> matching the section currently scrolled past the top.
No-ops on pages without #docs-toc.

gbStatic.css: add styles for .docs-toc / .docs-toc-row (position: sticky,
flex row for equal-height columns, link styling with active-state border).
All rules are scoped to the .docs-toc class so non-docs pages sharing
gbStatic.css are unaffected.

diff --git src/hg/htdocs/staticStyle/gbStatic.css src/hg/htdocs/staticStyle/gbStatic.css
index f841e8cebac..537dacd1055 100644
--- src/hg/htdocs/staticStyle/gbStatic.css
+++ src/hg/htdocs/staticStyle/gbStatic.css
@@ -1,371 +1,423 @@
 /* Genome Browser CSS for static pages
  *      Look and feel based on hgGateway/JWestDesign and GB menu styling
  *      This file is intended to be updateable outside of GB release cycle
  *      (settings here should not affect CGIs).
  *
  * Copyright (C) 2016 The Regents of the University of California
  */
 
 /* For conventions followed in this file, see README.txt */
 
 /* Colors */
 
 .gbsBlueLight{
     background-color: #4c759c;
 }
 
 .gbsGold {
      background-color: #eaca92;
 }
 
 .gbsGreyLight {
     background-color: #ededed;
 }
 
 .gbsGreyLighter {
     background-color: #f5f5f5;
 }
 
 .gbsYellowLight {
     background-color: #ffffe5;
 }
 
 .gbsRedDark {
     background-color: #7e1f16;
 }
 
 /* Text styling */
 
 .gbsWarnText {
     color: red;
     font-weight: bold;
 }
 
 /* Overall page styling */
 
 .gbsPage {
     line-height: 1.3;   /* current browser pages are 1.4 (a little dense), bootstrap is 1.2 */
     font-size: 15px;
     color: black;
 }
 
 /* Page header */
 .gbsPage h1 {
     padding: 5px 30px;
     /* needed to adjust margins after menu?  copying jwest.css here, with odd neg. margin */
     margin: 0 -16px 5px -16px; 
     background-color: #eaca92;  /* gold */
     color: black;
     font-size: 21px;    /* same as current static pages */
     font-weight: bold;
     /* font-weight: 500;   /* a little more subtle than bold */
 }
 
 /* Section header */
 .gbsPage h2 {
     padding: 6px 20px;
     background-color: #4c759c;  /* light blue */
     color: white;
     font-size: 17px;
     font-weight: bold;
 }
 
 .gbsPage h2:target {
     border: 3px solid black;
 }
 
 /* Subsection header */
 .gbsPage h3 {
     display: inline-block;      /* limits item width so background color doesn't span window */
     padding: 6px 20px;
     margin-bottom: 0;           /* needed to avoid stacking margins with inline-block */
     background-color: #dde6ee;  /* light slate blue-gray (lightened h2 color) */
     font-size: 17px;
     font-weight: bold;
 }
 
 .gbsPage hr {
     margin-left: 16px;
     border-style: inset;
 }
 
 /* Paragraph title */
 
 .gbsPage h6 {
     margin-top: 15px;
     margin-left: 15px;
     font-size: 15px;
     font-weight: bold;
 }
 
 /* Paragraph */
 .gbsPage p {
     margin: 15px 12px 0 15px;
 }
 
 /* Link */
 .gbsPage a {
      font-weight: bold;
 }
 
 /* Code */
 
 .gbsPage code {
     font-size: 15px;
     background-color: #ededed;          /* light gray */
     padding: 0 5px;
 }
 
 .gbsPage pre {
     /* width: 85%; */
     padding: 5px;
     padding-left: 8px;
     margin-left: 30px;
     line-height: normal;
     background-color: #ededed;          /* light gray */
 }
 
 .gbsPage pre > code {
     padding: 0;
 }
 
 /* Lists */
 
 .gbsPage li {
     margin-top: 8px;
 }
 
 /* Bulleted list */
 
 .gbsPage ul {
     margin-top: 8px;
     margin-left: 15px;
     list-style-type: none;      /* Use custom icons instead of bullets */
 }
 
 .gbsPage ul li {
     position: relative; /* from hgGateway */
 }
 
 .gbsPage ul li::before {   /* square bullets, from hgGateway */
     position: absolute;
     top: 0.4em;
     left: -1em;
     width: 8px;
     height: 8px;
     background-color: #7e1f16;  /* dark red */
     content: '';
 }
 
 /* List without bullets */
 
 .gbsPage ul.gbsNoBullet {
     padding-left: 20px;
 }
 
 .gbsPage ul.gbsNoBullet li::before {
     content: none;
 }
 
 /* Numbered list */
 
 .gbsPage ol {
     margin-top: 15px;
     margin-left: 6px;
 }
 
 .gbsPage ol li {
     margin-left: 10px;
 }
 
 /* Definition list */
 
 .gbsPage dl {
     margin: 0 12px 0 15px;
 }
 .gbsPage dt {
     margin-top: 15px;
 }
 
 /* Consider using this to reduce indents on lists within lists
 .gbsPage li li {
     margin-left: -15px;
 }
 */
 
 /* Tables */
 
 .gbsPage table {
     border: 2px solid gray;
     border-collapse: collapse;
     margin-top: 10px;
     margin-left: 15px;
     font-size: 13px;
 }
 
 table.gbsNoBorder {
     border: none;
 }
 
 table.gbsCenterText td {
     text-align: center;
 }
 
 .gbsPage th, td {
     text-align: left;
     padding: 1px 15px;
     border-bottom: 1px solid #ddd;
 }
 
 .gbsPage tr:hover {
     background-color: #ffffe5;          /* light yellow */
 }
 
 .gbsPage th {
     border-bottom: 2px solid gray;
     background-color: #ededed;          /* light gray */
 }
 
 /* Images */
 
 /* large images, e.g. figures, photos */
 
 .gbsPage img {
     border: 1px solid black;
     margin-left: 15px;
     margin-top: 10px;
 }
 
 /* small embedded image, e.g. for special characters or symbols */
 
 img.gbsInlineImg {
     border: 0;
     margin: 0;
 }
 
 p.gbsCaption {
     margin-top: 5px;
 }
 
 /* TODO: remove these two -- we should use bootstrap class text-right in wrapper element instead */
 
 p.gbsAlignRight {
     text-align: right;
 }
 
 img.gbsAlignRight {
     float: right !important;
 }
 
 /* Text alignment in table cells requires override in our version of bootstrap (revisit later) */
 /* TODO: Remove if confirmed unneeded.
 .gbsPage table text-center {
     text-align: center;
 }
 .gbsPage table text-right {
     text-align: right;
 }
 */
 
 /* Use UCSC Genome Browser 'bridge' logo as home link.
  * Suitable for static pages and CGI's without a top banner with logo.
  *
  * Copyright (C) 2016 The Regents of the University of California
  */
 
 /* TODO: Move to style/gbLogoInMenu.css for sharing with CGI's
 
 /* NOTE: negative positioning compensates for indents in parent rules */
 span#home-link {
     background-position: 0 0 !important;
     background-size: contain !important;
     background-image: url("../images/ucscHelixLogo.png") !important;
     background-repeat: no-repeat !important;
     top: -8px !important;
     width: 84px !important;
     height: 32px !important;
     background-color: white !important;
     margin-left: -9px !important;
 }
 
 /* Override nice-menu: from jWest*  */
 
 /* TODO: Move out of here after static page push. 
  * This is shared with CGI's. Currently also in gbAfterMenu.css */
 
 #main-menu-whole {
     background-color: #003a72 !important;
     font-family: Lato,Arial,Helvetica,sans-serif !important;
 }
 
 ul.nice-menu a {
     font-weight: normal !important;
     font-family: Lato,Arial,Helvetica,sans-serif !important;
 }
 
 ul.nice-menu ul li a {
     font-weight: normal !important;
     font-family: Lato,Arial,Helvetica,sans-serif !important;
 }
 
 /* Override (for now -- until gb.css can be updated in a release cycle */
 
 .gbDonateButton {
     margin-top: 3px;
     width: auto;
     height: auto;
     padding: 5px 20px;
 }
 
+/* Sticky sidebar table of contents for /docs/ pages */
+
+/* Flex row so the TOC column stretches to content height (Bootstrap 3 uses floats) */
+.docs-toc-row {
+    display: flex;
+}
+
+.docs-toc {
+    position: sticky;
+    top: 10px;
+    max-height: calc(100vh - 40px);
+    overflow-y: auto;
+    padding: 10px 0;
+    font-size: 14px;
+    border-right: 1px solid #ddd;
+}
+
+.docs-toc ul {
+    list-style: none;
+    padding-left: 0;
+    margin: 0;
+}
+
+.gbsPage .docs-toc ul li {
+    margin: 0;
+    padding: 0;
+}
+
+.gbsPage .docs-toc ul li::before {
+    content: none;
+}
+
+.gbsPage .docs-toc li a {
+    display: block;
+    padding: 4px 12px;
+    color: #333;
+    font-weight: normal;
+    text-decoration: none;
+    border-left: 3px solid transparent;
+}
+
+.gbsPage .docs-toc li a:hover {
+    color: #4c759c;
+    border-left-color: #ddd;
+}
+
+.gbsPage .docs-toc li.active > a {
+    color: #4c759c;
+    font-weight: bold;
+    border-left-color: #4c759c;
+}
+
 /* Bootstrap collapse component CSS (not included in our customized bootstrap.min.css) */
 .collapse {
     display: none;
 }
 
 .collapse.in {
     display: block;
 }
 
 .collapsing {
     position: relative;
     height: 0;
     overflow: hidden;
     transition-property: height, visibility;
     transition-duration: .35s;
     transition-timing-function: ease;
 }
 
 /* Styling for bootstrap collapsible section, used as follows:
 
 <div class="collapse-section">
 <a class="collapse-toggle" data-toggle="collapse" href=#collapseMe">Collapsible section</div>
 <div class="collapse" id="collapseMe">
 Stuff here
 </div>
 
 requires: jQuery.js and bootstrap.js
 */
 
 .collapse-section .collapse-toggle {
     text-decoration: none;
     margin: 15px 12px 0 0;
 }
 
 div.collapse-section .collapse-toggle {
     margin-left: 15px;  /* same as paragraph */
 }
 
 .collapse-section .collapse-toggle:after {
     vertical-align: -3px;
     font-family: FontAwesome;
     margin-left: 2px;
     color: lightgray;
 }
 
 .collapse-section .collapse-toggle:not(.collapsed):after {
     content: "\f0d7";
 }
 
 .collapse-section .collapse-toggle.collapsed:after {
     content: "\f0da";
 }