Repository navigation
Redesign of the Node.js API Docs聽#52343
Description
Activity
Can we move the external dependencies and tools to a different repo, and only keep the markdown documents in this repo? I imagine the new dependencies and build process could make the already flaky CI even more flaky and complicate releases and backports further if they end up in this repo (my brain already starts to hurt when thinking about backporting the tool changes to v18 and then make the addon docs build on SmartOS).
Can we move the external dependencies and tools to a different repo, and only keep the markdown documents in this repo? I imagine the new dependencies and build process could make the already flaky CI even more flaky and complicate releases and backports further if they end up in this repo (my brain already starts to hurt when thinking about backporting the tool changes to v18 and then make the addon docs build on SmartOS).
That is definitely doable. Didn't add to the initial proposal as Im not sure how the feeling/consensus about this one would be.
But I definitely would say a +1 to have the tooling somewhere else. The only issue is, generating the docs is part of Node.js build process (Makefile) so Im not sure how we should handle that transition? Would node core need to depend on another node repository and add it as part of the build process? That is currently out of my expertise but I can definitely 馃憖馃憖 into it!
+1 for proposal
if we do something like node-core-utils but on nodejs.org it's should work ?That is currently out of my expertise but I can definitely 馃憖馃憖 into it!
this would be possible either with direct github install instructions or npm publication - both pretty strightforward
But I definitely would say a +1 to have the tooling somewhere else. The only issue is, generating the docs is part of Node.js build process (Makefile) so Im not sure how we should handle that transition? Would node core need to depend on another node repository and add it as part of the build process? That is currently out of my expertise but I can definitely 馃憖馃憖 into it!
We can still keep a basic renderer here just to make sure that the docs are parsable, and also we still need to generate addon tests from addons.md.
Not sure if this is the right place to mention it, but during the summit I think several people mentioned in different sessions about our docs being too intimidating to beginners - I think by that they mean, API docs are like a dictionary, and you don't learn a language by reading a dictionary. We should have more tutorials in the docs before branching into the API dictionary. Which may affect the redesign because the page layout and information architecture etc. need to consider this.
Not sure if this is the right place to mention it, but during the summit I think several people mentioned in different sessions about our docs being too intimidating to beginners - I think by that they mean, API docs are like a dictionary, and you don't learn a language by reading a dictionary. We should have more tutorials in the docs before branching into the API dictionary. Which may affect the redesign because the page layout and information architecture etc. need to consider this.
I believe that's why we're cultivating an improved Learn section on nodejs.org :) I believe the API docs should be more an API reference, but agree they could be rewritten, improved, and have more examples... But that's not the scope of this issue.
126 remaining items
@mike-git374 You opened your message with accusations of bad faith. Feedback has been taken into account from many people already in this thread. If you want your feedback considered maybe try opening more politely and explain your reasoning clearly.
Reacted by Claudio Wunder, Sebastian Beltran and Colin IhrigFeedback has been taken into account from many people already in this thread
This is my point, 99.99% of users of these docs are not reading this thread, they are reading the actual docs, that's why I politely requested a banner linking to the new docs to help you get proper feedback. I politely listed my own feedback, that the ToC is the primary point of interest to the developer, it's what defines the API, and should not be stuck in a tiny column without proper formatting, and should not be hidden on less than 1280px window. I challenge you to find where I have not been absolutely polite in all interactions and where I have not explained my reasoning with clarity.
that's why I politely requested a banner linking to the new docs to help you get proper feedback
You're using your own individual experience as a rule of thumb, which is, by default biased. We won't be adding a banner at this point because the redesign is not even close to be ready for at-large rounds for feedback.
At the moment we're keeping feedback loops on GitHub, social medias such as LinkedIn, Twitter, Reddit and whatnot.
politely listed my own feedback, that the ToC is the primary point of interest to the developer, it's what defines the API, and should not be stuck in a tiny column without proper formatting, and should not be hidden on less than 1280px window.
That is your opinion and we respectfully disagree and we won't change that. Hearing feedback isn't the same as complying with feedback.
I challenge you to find where I have not been absolutely polite in all interactions and where I have not explained my reasoning with clarity.
You haven't been polite for a long while, with all due respect.
That said, we are going to make improvements based on your feedback, we just won't change the fact that on extra large screens it is going to a sidebar and on small screens it'd be on a collapsible accordion.
I'm not sure why you added this comment. We already shared we're working on adjusting the ToC, we already got your feedback.
Hello Node.js-ers! The Web Team has another exciting update for you:
We believe that the web generator is functionally complete, and are now in the final phase of the redesign: landing in
nodejs/node. We currently have a PR open (#62045), and hope to land the new generator very soon!Reacted by Adam Haglund, Daniel Perez and Brian MuenzenmeyerReacted by Aymen, Daniel Perez and Brian Muenzenmeyer
Hey, y'all 馃憢 with the redesign of the Node.js Website done. We're ready to move our efforts into revamping the design of the Node.js API docs and its build process.
We understand this is code owned by Node.js Core, so we're (@nodejs/web-infra) opening an issue here.
馃摚 Development Update (06.01.2026)
We're closer to the launch of the redesign of the Node.js API docs, we're currently ironing some quirk outs with UX, Speculative Requests, improving search functionality and ensuring everything is ready for launch.
TL;DR: Preview availabe at https://nodejs-api-docs-tooling.vercel.app/
Overview
Revamp of Tooling
nodejs/nodejs.devrepository as seen here and hereReactDOM(Server) to compile the JSX into plain HTML (initial rendering), which is then embedded in the HTML templates, making each page an HTML file. (Source MD file -> Target HTML file as it has been done so far).jsfilequery param and hashto signal to the Browser that these are different versions.outfolder (as described on themake-docMakefile step of the Node.js build process)Tooling Dependencies
preactas a JSX library (+ DOM rendering) since it's pretty much React but lightweight, it has pretty much 1:1 to React's API, and since the API docs are extremely simple statically generated page, we don't need anything fancierVitefor the build process, transpiling/compilation and output to HTML files, and for the availability of HMR/Dev Server. This will be an experiment.MDXto parse and transform the markdown into MDX/JSX.semver,might be needed.Revamp of Design
After the revamp of tooling is done, we have a 1:1 feature to the old generation of API docs, and we can generate the same API docs with the same styles, same layout, and same components (the HTML snippets transformed into React Components), we can proceed with the revamp of styles.
This means we would adopt these designs based on the Node.js Website redesign into the API Docs. These designs may still change and are pending @nodejs/tsc approval)
This part is blocked by the monorepo transformation of the Node.js Website repository, which would allow all the existing components to be bundled into a UI components package.
We aim to use Shiki as we use on the Node.js Website for the CodeBoxes and Tailwind and Radix UI for Component tooling and a11y as we've done on the Node.js Website.
This would fundamentally course-correct the current design of the API Docs. Note that we aim to add a Search box (as we've done on the Node.js Website) and restructure the API Docs as described on this initiative of the Next-10 initiative.
It is part of the redesign of the Node.js API Docs:
nodejs/nodejs.devtooling attached above as a reference)What is this issue about?
Keeping track of the efforts, communication, feedback, and progress of the revamp of the tooling and redesign of the API Docs is a sort of "Epic" for the whole initiative.
What's next?
Gathering initial feedback, consensus-seeking with Core Collaborators, and starting to delegate work on both fronts. Any support is welcome.
F.A.Q.
Are we going to translate the API docs?
No. It's an impossible and unmaintainable task. There is too much risk and work, and API docs get outdated fast. There is no merit in translating the API docs.
Can I help with the work on the API docs tooling?
Yes and no. We're more than open for feedback, ideas and code review, but the big chunk of work will be done by the Web Infra team which has a good knowledge of the tooling changes needed to be done and a good envisioning of what should be done.
Can I help with the redesign?
Yes! Implementation of components, designs, etc, is more than welcome! The actual components will reside on this repository and the Node.js Website. The API docs will only import the components/use them as the source will be on the Node.js Website repository.
Is there any timeline?
Not yet. We want to reach a consensus first and have a good understanding that the overall community is happy with these proposed changes + the proposed dependencies we want to use, such as MDX.
Edit (03/2026): While we still have no set date on our timeline, we've completed the implementation of the new "web" (HTML) generator, and should be able to replace the legacy HTML generator with it in a matter of weeks/months. We still have no timeline for the new JSON format.
With MDX are the source files changing?
No. The transform into MDX will happen only in memory during the build time as a build-step. So that we can transform the non-conforming YAML metadata into something React can use. The source files will be untouched.
What are the problems with the current tooling?
Hello Node.js-ers! The Web Team has another exciting update for you:
We believe that the web generator is functionally complete, and are now in the final phase of the redesign: landing in
nodejs/node. We currently have a PR open (#62045), and hope to land the new generator very soon!