doc: improve usability of API docs

nodejs · Jan 7, 2022 · 3898e6b · 3898e6b
1 parent f98e3b9
commit 3898e6b
Show file tree

Hide file tree

Showing 4 changed files with 120 additions and 10 deletions.
diff --git a/doc/api/index.md b/doc/api/index.md
@@ -10,6 +10,7 @@
 
 <hr class="line"/>
 
+* [Index](index.md)
 * [Assertion testing](assert.md)
 * [Asynchronous context tracking](async_context.md)
 * [Async hooks](async_hooks.md)

diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css
@@ -169,11 +169,31 @@ li.picker-header {
   position: relative;
 }
 
-li.picker-header:hover > a {
+li.picker-header .collapsed-arrow, li.picker-header .expanded-arrow {
+  width: 1.5ch;
+}
+
+li.picker-header .collapsed-arrow {
+  display: inline-block;
+}
+
+li.picker-header .expanded-arrow {
+  display: none;
+}
+
+li.picker-header.expanded .collapsed-arrow {
+  display: none;
+}
+
+li.picker-header.expanded .expanded-arrow {
+  display: inline-block;
+}
+
+li.picker-header.expanded > a {
   border-radius: 2px 2px 0 0;
 }
 
-li.picker-header:hover > .picker {
+li.picker-header.expanded > .picker {
   display: block;
   z-index: 1;
 }
@@ -223,6 +243,10 @@ li.picker-header a span {
   border-bottom-left-radius: 1px;
 }
 
+.gtoc-picker-header {
+  display: none;
+}
+
 .line {
   width: calc(100% - 1rem);
   display: block;
@@ -763,12 +787,33 @@ kbd {
 
 .header {
   position: sticky;
-  top: 0;
+  top: -1px;
+  padding-top: 1rem;
+}
+
+.header .pinner-header {
+  display: none;
+  margin-right: 0.4rem;
+  font-weight: 700;
+}
+
+.header.is-pinned {
   background-color: var(--color-fill-app);
-  padding-top: 1.5rem;
   z-index: 1;
 }
 
+.header.is-pinned .header-container {
+  display: none;
+}
+
+.header.is-pinned .pinner-header {
+  display: inline;
+}
+
+.header.is-pinned #gtoc {
+  margin: 0;
+}
+
 .header-container {
   display: flex;
   align-items: center;
@@ -786,6 +831,20 @@ kbd {
   outline: var(--brand3) dotted 2px;
 }
 
+@media only screen and (max-width: 576px) {
+  .header.is-pinned {
+    position: relative;
+  }
+
+  .header.is-pinned .header-container {
+    display: flex;
+  }
+
+  .header.is-pinned .pinner-header {
+    display: none;
+  }
+}
+
 @media only screen and (min-width: 577px) {
   #gtoc > ul > li {
     display: inline;
@@ -799,6 +858,18 @@ kbd {
     margin-right: 0;
     padding-right: 0;
   }
+
+  .header #gtoc > ul > li.pinner-header {
+    display: none;
+  }
+
+  .header.is-pinned #gtoc > ul > li.pinner-header {
+    display: inline;
+  }
+
+  #gtoc > ul > li.gtoc-picker-header {
+    display: none;
+  }
 }
 
 @media only screen and (max-width: 1024px) {
@@ -815,6 +886,10 @@ kbd {
   #column2 {
     display: none;
   }
+
+  #gtoc > ul > li.gtoc-picker-header {
+    display: inline;
+  }
 }
 
 .icon {

diff --git a/doc/template.html b/doc/template.html
@@ -39,16 +39,23 @@ <h1>Node.js __VERSION__ documentation</h1>
         </div>
         <div id="gtoc">
           <ul>
+            <li class="pinner-header">Node.js __VERSION__</li>
             <li class="picker-header">
-              <a href="#">Table of contents <span>&#x25bc;</span></a>
+              <a href="#">
+                <span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
+                Table of contents
+              </a>
 
-              <div class="picker">__TOC_PICKER__</div>              
+              <div class="picker">__TOC_PICKER__</div>
             </li>
             __ALTDOCS__
-            <li class="picker-header">
-              <a href="index.html">Index <span>&#x25bc;</span></a>
+            <li class="picker-header gtoc-picker-header">
+              <a href="#">
+                <span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
+                Index
+              </a>
 
-              <div class="picker">__GTOC__</div>              
+              <div class="picker">__GTOC__</div>
             </li>
             <li>
               <a href="all.html">View on single page</a>
@@ -104,6 +111,30 @@ <h1>Node.js __VERSION__ documentation</h1>
           );
         });
       }
+
+      // Handle pickers with click/taps rather than hovers
+      const pickers = document.querySelectorAll('.picker-header');
+      for(const picker of document.querySelectorAll('.picker-header')) {
+        picker.addEventListener('click', function() {
+          if(picker.classList.contains('expanded')) {
+            picker.classList.remove('expanded');
+          } else {
+            for(const other of pickers) {
+              other.classList.remove('expanded');
+            }
+
+            picker.classList.add('expanded');
+          }
+        });
+      }
+
+      // This snippet allows to track when the header is in sticky position
+      new IntersectionObserver(
+        ([e]) => {
+          e.target.classList.toggle("is-pinned", e.intersectionRatio < 1)
+        },
+        { threshold: [1] }
+      ).observe(document.querySelector(".header"));
     }
   </script>
 </body>

diff --git a/tools/doc/html.mjs b/tools/doc/html.mjs
@@ -511,7 +511,10 @@ function altDocs(filename, docCreated, versions) {
 
   return list ? `
     <li class="picker-header">
-      <a href="#">View another version <span>&#x25bc;</span></a>
+      <a href="#">
+        <span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
+        View another version
+      </a>
       <div class="picker"><ol id="alt-docs">${list}</ol></div>
     </li>
   ` : '';