Repository navigation
Documentation for 27.0.0-alpha.0.0.0 hidden #9254
Description
The "Docs" link in the header of https://nodejs.org/en links to https://nodejs.org/docs/latest/api/ and from there it's not possible to find the Node.js 27 docs.
Affected URL(s)
https://nodejs.org/docs/latest/api/
Description of the problem
Actual
https://nodejs.org/docs/latest/api/ displays the documentation for Node.js v26.13.0 with no link available for Node.js 27 Alpha
Expected
https://nodejs.org/docs/latest/api/ should include Node.js 27 under "Other versions" link.
Other
https://nodejs.org/en/blog/release/v27.0.0-alpha.0.0.0 was released on 2026-10-29.
There is a link in the blog post just above the SHASUMS section which has
Documentation: https://nodejs.org/docs/v27.0.0-alpha.0.0.0/api/
Activity
avivkeller commentedon Oct 31, 2026
Node.js v27.0.0-alpha released after Node.js v26.13.0, hence why it's version isn't in that list.
MikeMcC399 commentedon Oct 31, 2026
I've clarified that the problem comes from the https://nodejs.org/en linking to https://nodejs.org/docs/latest/api/
avivkeller commentedon Oct 31, 2026
(Removing
Bug, since technically this is expected, not a bug, but we should investigate solutions)ovflowd commentedon Oct 31, 2026
I'm unsure if this is NOT a bug, @avivkeller -- does doc-kit include "alpha" versions on its semver calculation for what versions to show when building the version dropdown?
Now, regarding nodejs.org/docs/latest/api not going to v27, I'm unsure if this is expected behavior. I believe the release-cloudflare-worker might need an update, so that it correctly marks redirect links.
@nodejs/releasers should alpha be included on what we use to determine "/docs/latest/" ?
So if a current version such as v26.14.0 releases on the 10th of November (for example) and then v27 alpha something releases on the 11th of November, should /latest/api go to Alpha?
Also are Alpha versions only for major version releases? or can there be an Alpha version of Node.js 26 and Node.js 24?
avivkeller commentedon Oct 31, 2026
Not at the moment, no, it probably should, but I would classify that more as a task than a bug, it's not misbehaving by not showing it, it was just never adjusted to. But, in any case, the semantics of it (to bug or not to bug) don't really matter.
I'm pre-emptively adding this to release agenda for insight.
MikeMcC399 commentedon Oct 31, 2026
Not according to the definition of
latestin https://github.com/nodejs/node#readmeAlpha is only for Node.js 27 and future release lines. It is not applicable to existing release lines 22, 24 & 26. See https://github.com/nodejs/release#readme for more detailed explanation. Also https://nodejs.org/en/blog/announcements/evolving-the-nodejs-release-schedule
ovflowd commentedon Oct 31, 2026
I think you misunderstood what I meant, assume Node 27 and 28 exist... Would only 28 receive alpha releases or would also 27 receive? Is alpha just for the next major release? or also for minor/patches?
ovflowd commentedon Oct 31, 2026
Right, then the current logic is right no? https://nodejs.org/docs/latest/api/ does link to latest "Current" version which is 26.13.0
MikeMcC399 commentedon Nov 1, 2026
My understanding of https://github.com/nodejs/release#readme and the phase diagram there, is that Alpha is only once at the beginning of a new release line, so only for the next major release, not for minor or patches.
MikeMcC399 commentedon Nov 1, 2026
Yes that seems rights to me. That is the version that most people will want to see.
The problem still remains that the Alpha documentation, for those who do want it, is not easily discoverable.
ovflowd commentedon Nov 1, 2026
That does seem a bug on the navigation menu on doc-kit as mentioned before hmmm; Will look into it.
MattIPv4 commentedon Nov 2, 2026
I don't think this is a bug -- as Aviv originally noted, 27.0.0-alpha.0.0.0 released after 26.13.0, and so at the time that 26.13.0 was statically generated, it had no knowledge of the non-existent 27.0.0-alpha.0.0.0 release to include it in the version dropdown.
That being said, this seems like a fair feature request! My suggestion in Slack had been that perhaps we should update the version dropdown to rehydrate itself client-side against index.json with any versions that it needs to show since the docs were originally generated.
ovflowd commentedon Nov 2, 2026
Ah... true. And the /latest/ API website goes to the latest Current. I misunderstood it.
Right... or... that's what the config endpoint could be for? To send patches... but IDK... I feel that the content (including dropdown) should be immutable. What could be is that the online hosted version of API docs on nodejs.org/api instead of being the one served from release assets, it is a living API version against
mainMattIPv4 commentedon Nov 2, 2026
Yeah, I agree in principle that the docs should be essentially immutable; that's why my suggestion would be a tiny bit of additive-only logic for new majors missing from the dropdown. I do not think we should implement a more generic patching system.
I'm also not keen on the idea of continually regenerating nodejs.org/api from
main, that feels like all sorts of problematic for the main docs that we show to folks to be continually changing in a way that does not match up with the version they'll actually be using locally.We could regenerate docs for all the active release lines when a new major is cut, but that again breaks the immutability of the docs. Perhaps this issue is really just a note to Releasers for future lines that it'd be good to cut the new major before cutting releases for the existing lines.
MikeMcC399 commentedon Nov 3, 2026
That is probably a tough restriction to follow. Although the process describes that the first Alpha release of a new release line is supposed to be released on the same day as the promotion of the previous release line from current to LTS, with a corresponding new release, in practice there can be last minute delays, as was the case last week.
MikeMcC399 commentedon Nov 3, 2026
On another point, I'm wondering how a link on the website could follow future Node.js 27 Alpha documentation releases
There is no directory on https://nodejs.org/docs/latest-v27.x/ and so https://nodejs.org/docs/latest-v27.x/api/ is also not available.
MikeMcC399 commentedon Nov 6, 2026
Follow nodejs/nodejs-latest-linker#26 for possible
latest-v27.xcreation.