Repository navigation
Implement real-time (on-load) updates to API docs live-environment #327
Description
Enter your suggestions in details:
One of the "flaws" (intentionally designed as-is) of our API docs is that once a release is done, docs cannot be udpated for said release or iterated over. This is due to the nature of our API docs release process and how its hosting is independent and completely static. There are advantages and disadvantages to this model.
For example, one of the disadvantages is, we cannot apply our global announcement banners over the course of time.
This proposal implements a static (resides on this repository or nodejs/node) api-docs.config.json that contains a map of entries for any given version of the Node.js API docs; Where the key is the current "major" the API doc was built and the value are the possible overrides such as:
- header banners (same mechanism from the website)
And then also global entries (not specific to version-specific changes):
- header banners (stays on top of the version-based banners)
And then the API Docs can also pool https://nodejs.org/dist/index.json or even https://nodejs.org/en/next-data/release-data to asynchronously completement the release dropdown with newer versions. So that people can navigate to newer versions of the docs.
All this data is loaded asynchronously and non-blocking.
Example structure of api-docs.config.json:
{
"global": {
"banner": {
"startDate": "2025-05-14T03:00:00.000Z",
"endDate": "2025-05-21T03:00:00.000Z",
"text": "May Security Release is available",
"link": "https://nodejs.org/en/blog/vulnerability/may-2025-security-releases",
"type": "warning"
}
}
"v24": {
"banner": {
"startDate": "2025-05-14T03:00:00.000Z",
"endDate": "2025-05-21T03:00:00.000Z",
"text": "May Security Release is available",
"link": "https://nodejs.org/en/blog/vulnerability/may-2025-security-releases",
"type": "warning"
}
}
}
Activity
ovflowd commentedon Jun 27, 2025
For the time being, I'm only thinking of banners, but we can definitely think on more changes.
ovflowd commentedon Jun 27, 2025
cc @nodejs/tsc -- this is also a solution for our ESP problem that our docs pages are not containing "Hey this version is EOL please use... blah blah"
AugustinMauroy commentedon Jul 15, 2025
also it's maybe usefull to keep version selection up to date
ovflowd commentedon Jul 15, 2025
Yes, but only for releases done after the current version that the doc is in so assume you have this being generated on 22.17.0:
Your menu would look like (assume Node.js v24 doesnt exist yet)
Then new versions v22.18.0 and v24.0.0 release:
The menu would look like this if you open the v22.17.0 docs: (https://nodejs.org/dist/v22.17.0/docs/api/)
The menu would look like this if you open the v22 docs: (https://nodejs.org/docs/latest-v22.x/api/)
In order words, it won't replace the v22.17.0 entry to v22.18.0 if you generated the v22.17.0 docs because v22.18.0 released, ensuring you're seeing the correct docs. This can be done by automatically integrating fetching our release metadata from our website on the docs, or something more perpetual such as the /dist/index.json
araujogui commentedon Apr 16, 2026
There's a second part of this issue: the release dropdown