doc: improve navigability of API docs

Author: ShogunPanda

doc/api_assets/style.css

@@ -159,56 +159,66 @@ em code {
   margin-bottom: 1rem;
 }
 
-#gtoc ul {
+#gtoc > ul {
   list-style: none;
   margin-left: 0;
   line-height: 1.5rem;
 }
 
-li.version-picker {
+li.picker-header {
   position: relative;
 }
 
-li.version-picker:hover > a {
+li.picker-header:hover > a {
   border-radius: 2px 2px 0 0;
 }
 
-li.version-picker:hover > ol {
+li.picker-header:hover > .picker {
   display: block;
   z-index: 1;
 }
 
-li.version-picker a span {
+li.picker-header a span {
   font-size: .7rem;
 }
 
-ol.version-picker {
+.picker {
   background-color: var(--color-fill-app);
   border: 1px solid var(--color-brand-secondary);
   border-radius: 0 0 2px 2px;
   display: none;
   list-style: none;
   position: absolute;
-  right: 0;
+  left: 0;
   top: 100%;
-  width: 100%;
+  width: max-content;
+  min-width: min(300px, 75vw);
+  max-width: 75vw;
+  max-height: min(600px, 60vh);
+  overflow-y: auto;
+}
+
+.picker > ul, .picker > ol {
+  list-style: none;
+  margin-left: 0;
+  line-height: 1.5rem;
 }
 
-#gtoc ol.version-picker li {
+.picker li {
   display: block;
   border-right: 0;
   margin-right: 0;
 }
 
-ol.version-picker li a {
+.picker li a {
   border-radius: 0;
   display: block;
   margin: 0;
   padding: .1rem;
   padding-left: 1rem;
 }
 
-ol.version-picker li:last-child a {
+.picker li:last-child a {
   border-bottom-right-radius: 1px;
   border-bottom-left-radius: 1px;
 }
@@ -219,6 +229,11 @@ ol.version-picker li:last-child a {
   padding-bottom: 1px;
 }
 
+.picker .line {
+  margin: 0;
+  width: 100%;
+}
+
 .api_stability {
   color: var(--white) !important;
   margin: 0 0 1rem;
@@ -499,6 +514,41 @@ hr {
   margin-top: .666rem;
 }
 
+.toc ul {
+  margin: 0
+}
+
+.toc li a::before {
+  content: "■";
+  color: var(--color-text-primary);
+  padding-right: 1em;
+  font-size: 0.9em;
+}
+
+.toc li a:hover::before {
+  color: var(--white);
+}
+
+.toc ul ul a {
+  padding-left: 1rem;
+}
+
+.toc ul ul ul a {
+  padding-left: 2rem;
+}
+
+.toc ul ul ul ul a {
+  padding-left: 3rem;
+}
+
+.toc ul ul ul ul ul a {
+  padding-left: 4rem;
+}
+
+.toc ul ul ul ul ul ul a {
+  padding-left: 5rem;
+}
+
 #toc .stability_0::after {
   background-color: var(--red2);
   color: var(--white);
@@ -711,10 +761,18 @@ kbd {
   }
 }
 
+.header {
+  position: sticky;
+  top: 0;
+  background-color: var(--color-fill-app);
+  padding-top: 1.5rem;
+  z-index: 1;
+}
+
 .header-container {
   display: flex;
   align-items: center;
-  margin: 1.5rem 0 1rem;
+  margin-bottom: 1rem;
   justify-content: space-between;
 }
 

doc/template.html

@@ -22,7 +22,7 @@
     </div>
 
     <div id="column1" data-id="__ID__" class="interior">
-      <header>
+      <header class="header">
         <div class="header-container">
           <h1>Node.js __VERSION__ documentation</h1>
           <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden>
@@ -39,16 +39,23 @@ <h1>Node.js __VERSION__ documentation</h1>
         </div>
         <div id="gtoc">
           <ul>
-            <li>
-              <a href="index.html">Index</a>
+            <li class="picker-header">
+              <a href="#">Table of contents <span>&#x25bc;</span></a>
+
+              <div class="picker">__TOC_PICKER__</div>              
+            </li>
+            __ALTDOCS__
+            <li class="picker-header">
+              <a href="index.html">Index <span>&#x25bc;</span></a>
+
+              <div class="picker">__GTOC__</div>              
             </li>
             <li>
               <a href="all.html">View on single page</a>
             </li>
             <li>
               <a href="__FILENAME__.json">View as JSON</a>
             </li>
-            __ALTDOCS__
             __EDIT_ON_GITHUB__
           </ul>
         </div>

tools/doc/html.mjs

@@ -98,8 +98,9 @@ export function toHTML({ input, content, filename, nodeVersion, versions }) {
                      .replace(/__FILENAME__/g, filename)
                      .replace('__SECTION__', content.section)
                      .replace(/__VERSION__/g, nodeVersion)
-                     .replace('__TOC__', content.toc)
-                     .replace('__GTOC__', gtocHTML.replace(
+                     .replace(/__TOC__/g, content.toc)
+                     .replace(/__TOC_PICKER__/g, content.tocPicker)
+                     .replace(/__GTOC__/g, gtocHTML.replace(
                        `class="nav-${id}"`, `class="nav-${id} active"`))
                      .replace('__EDIT_ON_GITHUB__', editOnGitHub(filename))
                      .replace('__CONTENT__', processContent(content));
@@ -442,17 +443,18 @@ export function buildToc({ filename, apilinks }) {
     });
 
     if (toc !== '') {
-      file.toc = '<details id="toc" open><summary>Table of contents</summary>' +
-        unified()
-          .use(markdown)
-          .use(gfm)
-          .use(remark2rehype, { allowDangerousHtml: true })
-          .use(raw)
-          .use(htmlStringify)
-          .processSync(toc).toString() +
-        '</details>';
+      const inner = unified()
+        .use(markdown)
+        .use(gfm)
+        .use(remark2rehype, { allowDangerousHtml: true })
+        .use(raw)
+        .use(htmlStringify)
+        .processSync(toc).toString();
+
+      file.toc = `<details id="toc" open><summary>Table of contents</summary>${inner}</details>`;
+      file.tocPicker = `<div class="toc">${inner}</div>`;
     } else {
-      file.toc = '<!-- TOC -->';
+      file.toc = file.tocPicker = '<!-- TOC -->';
     }
   };
 }
@@ -508,9 +510,9 @@ function altDocs(filename, docCreated, versions) {
   const list = versions.filter(isDocInVersion).map(wrapInListItem).join('\n');
 
   return list ? `
-    <li class="version-picker">
+    <li class="picker-header">
       <a href="#">View another version <span>&#x25bc;</span></a>
-      <ol class="version-picker">${list}</ol>
+      <div class="picker"><ol id="alt-docs">${list}</ol></div>
     </li>
   ` : '';
 }