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"
}
}
}
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.jsonthat 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:And then also global entries (not specific to version-specific changes):
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" } } }