Docs only shows version subset in navigation

Browser version: Chrome Version 80.0.3987.106
Operating system: macOS 10.14

When viewing a given API reference on the website, there's an option to view another version:

It allows for a user to pick another version to swap to and see relevant docs, but it's constrained by what existed at the time the currently chosen doc was written. This means that e.g when a user picks v11.x, they won't be able to go back to v13.x:

without first going back to v12.x.

I'd say this is an antipattern, and that we should unilaterally be storing the versions available in the most recently defined major line. If this seems like a good path forward, i'm happy to implement this myself!

I'd say this is an antipattern, and that we should unilaterally be storing the versions available in the most recently defined major line. If this seems like a good path forward, i'm happy to implement this myself!

I agree.

@Trott

@Trott do you want to transfer this one to the Node repo? I think this needs to be fixed there since it's for the API docs generated there

@codebytere

+1 from me.

@codebytere If you haven't already discovered it, the existing drop down is generated at build time here:

node/tools/doc/html.js

Lines 394 to 412 in 8429295

    
           async function altDocs(filename, docCreated) { 
        
             const [, docCreatedMajor, docCreatedMinor] = docCreated.map(Number); 
        
             const host = 'https://nodejs.org'; 
        
             const versions = await getVersions.versions(); 
        
             const getHref = (versionNum) => 
        
               `${host}/docs/latest-v${versionNum}/api/${filename}.html`; 
        
             const wrapInListItem = (version) => 
        
               `<li><a href="${getHref(version.num)}">${version.num}` + 
        
               `${version.lts ? ' <b>LTS</b>' : ''}</a></li>`; 
        
             function isDocInVersion(version) { 
        
               const [versionMajor, versionMinor] = version.num.split('.').map(Number); 
        
               if (docCreatedMajor > versionMajor) return false; 
        
               if (docCreatedMajor < versionMajor) return true; 
        
               if (Number.isNaN(versionMinor)) return true; 
        
               return docCreatedMinor <= versionMinor; 
        
             }

@Trott

@Trott do you want to transfer this one to the Node repo? I

I'll let @codebytere move it if she wants to. Wherever it makes the most sense for her. (Argument for this repository might be that people noticing the problem are likely to look here for an issue about it. Argument for the core repository is that's where the work might have to happen. Although I can also imagine changing things there so that the menu is generated here instead. I don't know.)

@richardlau

@richardlau do you know where website logging occurs? Preliminary poking around indicated that it's falling back to local file read 100% of the time to show versions, meaning that the https call to read the changelog from master isn't working 🤔

@richardlau

@richardlau do you know where website logging occurs? Preliminary poking around indicated that it's falling back to local file read 100% of the time to show versions, meaning that the https call to read the changelog from master isn't working 🤔

I'm not sure what logging you're asking for.

The code that does the https call is in https://github.com/nodejs/node/blob/master/tools/doc/versions.js.

right, yes, that's what i'm referencing. e.g if i'm correct and

console.warn(Unable to retrieve ${url}. Falling back to ${file}.);

is being hit, where would that be logged to?

right, yes, that's what i'm referencing. e.g if i'm correct and

console.warn(Unable to retrieve ${url}. Falling back to ${file}.);

is being hit, where would that be logged to?

stderr usually.

e.g. if I edit the URL so it's not found:

diff --git a/tools/doc/versions.js b/tools/doc/versions.js
index 782ce90..d57baf7 100644
--- a/tools/doc/versions.js
+++ b/tools/doc/versions.js
@@ -42,7 +42,7 @@ module.exports = {
     // The CHANGELOG.md on release branches may not reference newer semver
     // majors of Node.js so fetch and parse the version from the master branch.
     const url =
-      'https://raw.githubusercontent.com/nodejs/node/master/CHANGELOG.md';
+      'https://raw.githubusercontent.com/nodejs/node/master/CHANGELOG0.md';
     let changelog;
     const file = path.join(srcRoot, 'CHANGELOG.md');
     if (kNoInternet) {

then

-bash-4.2$ NODE=out/Release/node make doc-only
npm WARN prepare removing existing node_modules/ before installation
added 105 packages in 1.403s
mkdir -p out/doc/api
cp -r doc/api out/doc
make[1]: Entering directory `/home/users/riclau/sandbox/github/nodejs'
if [ -x /home/users/riclau/sandbox/github/nodejs/out/Release/node ] && [ -e /home/users/riclau/sandbox/github/nodejs/out/Release/node ]; then /home/users/riclau/sandbox/github/nodejs/out/Release/node  tools/doc/apilinks.js out/doc/apilinks.json lib/_http_client.js lib/net.js lib/_tls_wrap.js lib/http.js lib/dns.js lib/tls.js lib/fs.js lib/path.js lib/domain.js lib/timers.js lib/_http_outgoing.js lib/events.js lib/child_process.js lib/_http_agent.js lib/tty.js lib/querystring.js lib/async_hooks.js lib/url.js lib/http2.js lib/https.js lib/zlib.js lib/perf_hooks.js lib/_stream_readable.js lib/buffer.js lib/punycode.js lib/trace_events.js lib/cluster.js lib/_stream_duplex.js lib/process.js lib/_http_common.js lib/stream.js lib/sys.js lib/_http_incoming.js lib/_stream_passthrough.js lib/_stream_writable.js lib/repl.js lib/string_decoder.js lib/constants.js lib/v8.js lib/assert.js lib/_stream_wrap.js lib/util.js lib/_stream_transform.js lib/wasi.js lib/module.js lib/vm.js lib/console.js lib/crypto.js lib/inspector.js lib/_http_server.js lib/os.js lib/dgram.js lib/readline.js lib/worker_threads.js lib/_tls_common.js; elif [ -x `which node` ] && [ -e `which node` ] && [ `which node` ]; then `which node`  tools/doc/apilinks.js out/doc/apilinks.json lib/_http_client.js lib/net.js lib/_tls_wrap.js lib/http.js lib/dns.js lib/tls.js lib/fs.js lib/path.js lib/domain.js lib/timers.js lib/_http_outgoing.js lib/events.js lib/child_process.js lib/_http_agent.js lib/tty.js lib/querystring.js lib/async_hooks.js lib/url.js lib/http2.js lib/https.js lib/zlib.js lib/perf_hooks.js lib/_stream_readable.js lib/buffer.js lib/punycode.js lib/trace_events.js lib/cluster.js lib/_stream_duplex.js lib/process.js lib/_http_common.js lib/stream.js lib/sys.js lib/_http_incoming.js lib/_stream_passthrough.js lib/_stream_writable.js lib/repl.js lib/string_decoder.js lib/constants.js lib/v8.js lib/assert.js lib/_stream_wrap.js lib/util.js lib/_stream_transform.js lib/wasi.js lib/module.js lib/vm.js lib/console.js lib/crypto.js lib/inspector.js lib/_http_server.js lib/os.js lib/dgram.js lib/readline.js lib/worker_threads.js lib/_tls_common.js; else echo "No available node, cannot run \"node  tools/doc/apilinks.js out/doc/apilinks.json lib/_http_client.js lib/net.js lib/_tls_wrap.js lib/http.js lib/dns.js lib/tls.js lib/fs.js lib/path.js lib/domain.js lib/timers.js lib/_http_outgoing.js lib/events.js lib/child_process.js lib/_http_agent.js lib/tty.js lib/querystring.js lib/async_hooks.js lib/url.js lib/http2.js lib/https.js lib/zlib.js lib/perf_hooks.js lib/_stream_readable.js lib/buffer.js lib/punycode.js lib/trace_events.js lib/cluster.js lib/_stream_duplex.js lib/process.js lib/_http_common.js lib/stream.js lib/sys.js lib/_http_incoming.js lib/_stream_passthrough.js lib/_stream_writable.js lib/repl.js lib/string_decoder.js lib/constants.js lib/v8.js lib/assert.js lib/_stream_wrap.js lib/util.js lib/_stream_transform.js lib/wasi.js lib/module.js lib/vm.js lib/console.js lib/crypto.js lib/inspector.js lib/_http_server.js lib/os.js lib/dgram.js lib/readline.js lib/worker_threads.js lib/_tls_common.js\""; exit 1; fi;
if [ -x /home/users/riclau/sandbox/github/nodejs/out/Release/node ] && [ -e /home/users/riclau/sandbox/github/nodejs/out/Release/node ]; then /home/users/riclau/sandbox/github/nodejs/out/Release/node  tools/doc/generate.js --node-version=v14.0.0 --apilinks=out/doc/apilinks.json doc/api/path.md --output-directory=out/doc/api; elif [ -x `which node` ] && [ -e `which node` ] && [ `which node` ]; then `which node`  tools/doc/generate.js --node-version=v14.0.0 --apilinks=out/doc/apilinks.json doc/api/path.md --output-directory=out/doc/api; else echo "No available node, cannot run \"node  tools/doc/generate.js --node-version=v14.0.0 --apilinks=out/doc/apilinks.json doc/api/path.md --output-directory=out/doc/api\""; exit 1; fi;
Unable to retrieve https://raw.githubusercontent.com/nodejs/node/master/CHANGELOG0.md. Falling back to /home/users/riclau/sandbox/github/nodejs/CHANGELOG.md.
...

yes haha sorry i don't think i'm asking this question well - On the website itself, when that codepath is executed, where should i be going to confirm that the error is being logged to stderr?

E.g in Electron we use papertrail for our website logging - that's where i'd go to track down an issue of this nature. Where is that analogous logging for Node.js' website? does it exist?

yes haha sorry i don't think i'm asking this question well - On the website itself, when that codepath is executed, where should i be going to confirm that the error is being logged to stderr?

It isn't? The drop down is a static list generated when the API docs are built. So the code I've been linking to only ever runs on the release machine.

E.g in Electron we use papertrail for our website logging - that's where i'd go to track down an issue of this nature. Where is that analogous logging for Node.js' website? does it exist?

¯\_(ツ)_/¯ I don't know. Maybe someone from @nodejs/website or @nodejs/build-infra does.

AFAICT this stuff is only logged during build time; the toggler is static, no JS is involved client-side apart from the highlighting library (SHJS).

I'm not sure that we have some system for logs in any of nodejs websites. It's overhead for simple websites, that not contains any specific functionality.

@codebytere

@codebytere what you're looking for is in ci-release, in your release job, the docs are generated by the "sources" builder (specifically centos7-release-sources), so navigate to that one and look at the full console log and you'll find tools/doc/generate.js output in there. So for your 13.10.0 build you can see this in: https://ci-release.nodejs.org/job/iojs+release/5706/nodes=centos7-release-sources/consoleFull
If you want to test out any code changes here then feel free to run some test jobs through ci-release from your fork since you have access to do so, just make sure you select "test" from the dropdown and use the proper 10-char commit hash and proper date and it should show up nicely in https://nodejs.org/download/test/ (edit: there's up to a 5 minute delay from completion of a builder to publishing the resources, so if centos7-release-sources finishes but you don't see your docs or even your new directory, be patient).

Some thoughts about this:

This needs to work offline and away from nodejs.org, docs should be usable as purely static resources. Which explains why it is the way that it is. But doesn't preclude there being better options for upgrading the UX when it can.
Instead of doing this at build time, have a mode that's "if I'm online and can fetch resources from nodejs.org, fetch nodejs.org/download/release/index.json, form a release line menu from that and show it". People reading the docs from nodejs.org should be able to make fetch calls to that JSON file and it should be pretty simple to parse it down into a release line selector list.

@rvagg

Awesome, that's exactly what i was after @rvagg! I'll start with that approach.

tools,doc: move version picker to external file

tools: move version picker script to main doc directory

This issue has been marked as stale due to 210 days of inactivity.
It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.

This issue has been automatically closed after 30 days of inactivity following its stale status (no activity for a total of 120 days).
If this is still relevant, feel free to reopen it or leave a comment with additional details so we can continue the discussion.

Navigation Menu

Repository navigation

Docs only shows version subset in navigation #32077

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	async function altDocs(filename, docCreated) {
	const [, docCreatedMajor, docCreatedMinor] = docCreated.map(Number);
	const host = 'https://nodejs.org';
	const versions = await getVersions.versions();

	const getHref = (versionNum) =>
	`${host}/docs/latest-v${versionNum}/api/${filename}.html`;

	const wrapInListItem = (version) =>
	`<li><a href="${getHref(version.num)}">${version.num}` +
	`${version.lts ? ' <b>LTS</b>' : ''}</a></li>`;

	function isDocInVersion(version) {
	const [versionMajor, versionMinor] = version.num.split('.').map(Number);
	if (docCreatedMajor > versionMajor) return false;
	if (docCreatedMajor < versionMajor) return true;
	if (Number.isNaN(versionMinor)) return true;
	return docCreatedMinor <= versionMinor;
	}

Docs only shows version subset in navigation #32077

Description

Activity

Trott commented on Mar 3, 2020

nschonni commented on Mar 3, 2020

richardlau commented on Mar 3, 2020

Trott commented on Mar 4, 2020

codebytere commented on Mar 4, 2020

richardlau commented on Mar 4, 2020

codebytere commented on Mar 4, 2020

richardlau commented on Mar 4, 2020

codebytere commented on Mar 4, 2020

richardlau commented on Mar 4, 2020

XhmikosR commented on Mar 4, 2020

alexandrtovmach commented on Mar 4, 2020

rvagg commented on Mar 4, 2020

codebytere commented on Mar 4, 2020

github-actions commented on Jun 27, 2026

github-actions commented on Jul 28, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions