From 9c4f457da2edaef7e3dc7a8722944a9edbdca491 Mon Sep 17 00:00:00 2001 From: Shogun Date: Wed, 5 Jan 2022 14:36:50 +0100 Subject: [PATCH] doc: improve navigability of API docs --- doc/api_assets/style.css | 82 ++++++++++++++++++++++++++++++++++------ doc/template.html | 15 ++++++-- tools/doc/html.mjs | 30 ++++++++------- 3 files changed, 97 insertions(+), 30 deletions(-) diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css index 90db2f4bd8a66b..0eb5125dc5aa68 100644 --- a/doc/api_assets/style.css +++ b/doc/api_assets/style.css @@ -159,48 +159,58 @@ 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; @@ -208,7 +218,7 @@ ol.version-picker li a { 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; } diff --git a/doc/template.html b/doc/template.html index 5e70b6054e080b..af064be8b22afa 100644 --- a/doc/template.html +++ b/doc/template.html @@ -22,7 +22,7 @@
-
+

Node.js __VERSION__ documentation

diff --git a/tools/doc/html.mjs b/tools/doc/html.mjs index 8d356836eb5667..f965a26cfed2f1 100644 --- a/tools/doc/html.mjs +++ b/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 = '
Table of contents' + - unified() - .use(markdown) - .use(gfm) - .use(remark2rehype, { allowDangerousHtml: true }) - .use(raw) - .use(htmlStringify) - .processSync(toc).toString() + - '
'; + const inner = unified() + .use(markdown) + .use(gfm) + .use(remark2rehype, { allowDangerousHtml: true }) + .use(raw) + .use(htmlStringify) + .processSync(toc).toString(); + + file.toc = `
Table of contents${inner}
`; + file.tocPicker = `
${inner}
`; } else { - file.toc = ''; + file.toc = file.tocPicker = ''; } }; } @@ -508,9 +510,9 @@ function altDocs(filename, docCreated, versions) { const list = versions.filter(isDocInVersion).map(wrapInListItem).join('\n'); return list ? ` -
  • +
  • View another version ▼ -
      ${list}
    +
      ${list}
    • ` : ''; }