Skip to content

Commit 3898e6b

Browse files
ShogunPandaShogunPanda
committed
doc: improve usability of API docs
1 parent f98e3b9 commit 3898e6b

4 files changed

Lines changed: 120 additions & 10 deletions

File tree

‎doc/api/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010

1111
<hr class="line"/>
1212

13+
* [Index](index.md)
1314
* [Assertion testing](assert.md)
1415
* [Asynchronous context tracking](async_context.md)
1516
* [Async hooks](async_hooks.md)

‎doc/api_assets/style.css‎

Lines changed: 79 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -169,11 +169,31 @@ li.picker-header {
169169
position: relative;
170170
}
171171

172-
li.picker-header:hover > a {
172+
li.picker-header .collapsed-arrow, li.picker-header .expanded-arrow {
173+
width: 1.5ch;
174+
}
175+
176+
li.picker-header .collapsed-arrow {
177+
display: inline-block;
178+
}
179+
180+
li.picker-header .expanded-arrow {
181+
display: none;
182+
}
183+
184+
li.picker-header.expanded .collapsed-arrow {
185+
display: none;
186+
}
187+
188+
li.picker-header.expanded .expanded-arrow {
189+
display: inline-block;
190+
}
191+
192+
li.picker-header.expanded > a {
173193
border-radius: 2px 2px 0 0;
174194
}
175195

176-
li.picker-header:hover > .picker {
196+
li.picker-header.expanded > .picker {
177197
display: block;
178198
z-index: 1;
179199
}
@@ -223,6 +243,10 @@ li.picker-header a span {
223243
border-bottom-left-radius: 1px;
224244
}
225245

246+
.gtoc-picker-header {
247+
display: none;
248+
}
249+
226250
.line {
227251
width: calc(100% - 1rem);
228252
display: block;
@@ -763,12 +787,33 @@ kbd {
763787

764788
.header {
765789
position: sticky;
766-
top: 0;
790+
top: -1px;
791+
padding-top: 1rem;
792+
}
793+
794+
.header .pinner-header {
795+
display: none;
796+
margin-right: 0.4rem;
797+
font-weight: 700;
798+
}
799+
800+
.header.is-pinned {
767801
background-color: var(--color-fill-app);
768-
padding-top: 1.5rem;
769802
z-index: 1;
770803
}
771804

805+
.header.is-pinned .header-container {
806+
display: none;
807+
}
808+
809+
.header.is-pinned .pinner-header {
810+
display: inline;
811+
}
812+
813+
.header.is-pinned #gtoc {
814+
margin: 0;
815+
}
816+
772817
.header-container {
773818
display: flex;
774819
align-items: center;
@@ -786,6 +831,20 @@ kbd {
786831
outline: var(--brand3) dotted 2px;
787832
}
788833

834+
@media only screen and (max-width: 576px) {
835+
.header.is-pinned {
836+
position: relative;
837+
}
838+
839+
.header.is-pinned .header-container {
840+
display: flex;
841+
}
842+
843+
.header.is-pinned .pinner-header {
844+
display: none;
845+
}
846+
}
847+
789848
@media only screen and (min-width: 577px) {
790849
#gtoc > ul > li {
791850
display: inline;
@@ -799,6 +858,18 @@ kbd {
799858
margin-right: 0;
800859
padding-right: 0;
801860
}
861+
862+
.header #gtoc > ul > li.pinner-header {
863+
display: none;
864+
}
865+
866+
.header.is-pinned #gtoc > ul > li.pinner-header {
867+
display: inline;
868+
}
869+
870+
#gtoc > ul > li.gtoc-picker-header {
871+
display: none;
872+
}
802873
}
803874

804875
@media only screen and (max-width: 1024px) {
@@ -815,6 +886,10 @@ kbd {
815886
#column2 {
816887
display: none;
817888
}
889+
890+
#gtoc > ul > li.gtoc-picker-header {
891+
display: inline;
892+
}
818893
}
819894

820895
.icon {

‎doc/template.html‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,16 +39,23 @@ <h1>Node.js __VERSION__ documentation</h1>
3939
</div>
4040
<div id="gtoc">
4141
<ul>
42+
<li class="pinner-header">Node.js __VERSION__</li>
4243
<li class="picker-header">
43-
<a href="#">Table of contents <span>&#x25bc;</span></a>
44+
<a href="#">
45+
<span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
46+
Table of contents
47+
</a>
4448

45-
<div class="picker">__TOC_PICKER__</div>
49+
<div class="picker">__TOC_PICKER__</div>
4650
</li>
4751
__ALTDOCS__
48-
<li class="picker-header">
49-
<a href="index.html">Index <span>&#x25bc;</span></a>
52+
<li class="picker-header gtoc-picker-header">
53+
<a href="#">
54+
<span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
55+
Index
56+
</a>
5057

51-
<div class="picker">__GTOC__</div>
58+
<div class="picker">__GTOC__</div>
5259
</li>
5360
<li>
5461
<a href="all.html">View on single page</a>
@@ -104,6 +111,30 @@ <h1>Node.js __VERSION__ documentation</h1>
104111
);
105112
});
106113
}
114+
115+
// Handle pickers with click/taps rather than hovers
116+
const pickers = document.querySelectorAll('.picker-header');
117+
for(const picker of document.querySelectorAll('.picker-header')) {
118+
picker.addEventListener('click', function() {
119+
if(picker.classList.contains('expanded')) {
120+
picker.classList.remove('expanded');
121+
} else {
122+
for(const other of pickers) {
123+
other.classList.remove('expanded');
124+
}
125+
126+
picker.classList.add('expanded');
127+
}
128+
});
129+
}
130+
131+
// This snippet allows to track when the header is in sticky position
132+
new IntersectionObserver(
133+
([e]) => {
134+
e.target.classList.toggle("is-pinned", e.intersectionRatio < 1)
135+
},
136+
{ threshold: [1] }
137+
).observe(document.querySelector(".header"));
107138
}
108139
</script>
109140
</body>

‎tools/doc/html.mjs‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -511,7 +511,10 @@ function altDocs(filename, docCreated, versions) {
511511

512512
return list ? `
513513
<li class="picker-header">
514-
<a href="#">View another version <span>&#x25bc;</span></a>
514+
<a href="#">
515+
<span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
516+
View another version
517+
</a>
515518
<div class="picker"><ol id="alt-docs">${list}</ol></div>
516519
</li>
517520
` : '';

0 commit comments

Comments
 (0)