From 9928d1cf21c8bf57af674344af41db887e8332f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= Date: Sun, 12 Jul 2026 23:47:46 -0300 Subject: [PATCH 1/8] feat: create api docs beta announcement blog post --- apps/site/authors.json | 5 +++ .../blog/announcements/new-api-docs-beta.md | 37 +++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 apps/site/pages/en/blog/announcements/new-api-docs-beta.md diff --git a/apps/site/authors.json b/apps/site/authors.json index e3901173461df..03624328fa640 100644 --- a/apps/site/authors.json +++ b/apps/site/authors.json @@ -113,6 +113,11 @@ "name": "Giovanny Gongora", "website": "https://github.com/Gioyik" }, + "Guilherme Araújo": { + "id": "araujogui", + "name": "Guilherme Araújo", + "website": "https://github.com/araujogui" + }, "Isaac Schlueter": { "id": "isaacs", "name": "Isaac Schlueter", diff --git a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md new file mode 100644 index 0000000000000..b4c417cac2612 --- /dev/null +++ b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md @@ -0,0 +1,37 @@ +--- +date: '2026-07-12T12:00:00.000Z' +category: announcements +title: Try the New Node.js API Documentation Beta +layout: blog-post +author: Guilherme Araújo +--- + +We've been rebuilding how Node.js generates and presents its API documentation, and a preview is now live at [beta.docs.nodejs.org](https://beta.docs.nodejs.org/). Before it becomes the default, we want as many people as possible to use it for real work and tell us what's their feeedback. + +## What's different for readers + +The content itself hasn't changed: every page is generated from the same Markdown files in the [nodejs/node](https://github.com/nodejs/node) repository that power the current docs. The features you rely on today made the trip too: light and dark themes, ESM/CJS switching on code examples, copy buttons on snippets, stability badges, and version history. + +The redesign goes deeper than visuals, though: navigation, layout, and readability were all reworked so that finding and understanding an API takes less effort. On top of that, the beta adds things the current docs have never had: + +- **Search**: For the first time, the API docs have built-in search. A search box on every page, with a keyboard shortcut, lets you jump anywhere in the API without a detour through a search engine. +- **One design across the project**: The API docs now shares the design system of the nodejs.org website, with a persistent sidebar listing every module, an always-visible per-page table of contents, and a layout that works on small screens. +- **Docs as Markdown**: Every page can now be viewed as plain Markdown, a format that AI tools like Claude Code and Codex can work with natively. Point them at a page and they can read it as is, with no HTML scraping in between. + +And that's not the whole list: the beta also ships features like reading times, announcement bars, [llms.txt](https://nodejs.org/llms.txt) etc. + +We also care about the needs of every user, and we pay attention to the ones that are easy to overlook. Every page stays usable even with JavaScript disabled and offline. + +## Same content, new tooling + +Under the hood, the beta is built with [doc-kit](https://github.com/nodejs/doc-kit), a standalone tool built to replace the current documentation generator, which has lived inside Node.js core for years. It parses the existing Markdown files and can produce several outputs from them: the redesigned web pages you see on the beta, plus the legacy HTML, JSON, man-page formats etc. Existing consumers of those formats keep working during the transition, and contributors keep editing the same Markdown files they always have. + +There's a broader goal here too: any project can pick up doc-kit for its own documentation, inside or outside the Node.js ecosystem. And that's already happening. The [undici docs](https://undici.nodejs.org/) are built with doc-kit today, and [webpack is migrating](https://github.com/webpack/webpack-doc-kit) its API documentation as well. + +If you're curious about the design and progress of the effort, the tracking issue at [nodejs/node#52343](https://github.com/nodejs/node/issues/52343) has the full picture. + +## We need your feedback + +This is a beta, and we're publishing it early because we want people using it and giving us feedback, so we can iterate before the new docs replace the current ones. If you spend time in the API docs, try spending it on [beta.docs.nodejs.org](https://beta.docs.nodejs.org/) for a while and let us know how it goes. + +Please open an issue on the [nodejs/doc-kit](https://github.com/nodejs/doc-kit/issues) repository with anything you find, big or small. The current documentation remains in place in the meantime, so nothing changes for you today — but with your help, the new docs will be ready to take over soon. From 44dcc8f5126403a4f284a8ac8c6c2757dbed2468 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= Date: Mon, 13 Jul 2026 00:04:20 -0300 Subject: [PATCH 2/8] feat: add ack section --- .../pages/en/blog/announcements/new-api-docs-beta.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md index b4c417cac2612..f07b362815068 100644 --- a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md +++ b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md @@ -6,11 +6,11 @@ layout: blog-post author: Guilherme Araújo --- -We've been rebuilding how Node.js generates and presents its API documentation, and a preview is now live at [beta.docs.nodejs.org](https://beta.docs.nodejs.org/). Before it becomes the default, we want as many people as possible to use it for real work and tell us what's their feeedback. +We've been rebuilding how Node.js generates and presents its API documentation, and a preview is now live at [beta.docs.nodejs.org](https://beta.docs.nodejs.org/). Before it becomes the default, we want as many people as possible to use it for real work and tell us what you think. ## What's different for readers -The content itself hasn't changed: every page is generated from the same Markdown files in the [nodejs/node](https://github.com/nodejs/node) repository that power the current docs. The features you rely on today made the trip too: light and dark themes, ESM/CJS switching on code examples, copy buttons on snippets, stability badges, and version history. +The content itself hasn't changed: every page is generated from the same Markdown files in the [nodejs/node](https://github.com/nodejs/node) repository that power the current docs. The features you rely on today made the trip too: light and dark themes, ESM/CJS switching and copy buttons on snippets, stability badges, and version history. The redesign goes deeper than visuals, though: navigation, layout, and readability were all reworked so that finding and understanding an API takes less effort. On top of that, the beta adds things the current docs have never had: @@ -24,7 +24,9 @@ We also care about the needs of every user, and we pay attention to the ones tha ## Same content, new tooling -Under the hood, the beta is built with [doc-kit](https://github.com/nodejs/doc-kit), a standalone tool built to replace the current documentation generator, which has lived inside Node.js core for years. It parses the existing Markdown files and can produce several outputs from them: the redesigned web pages you see on the beta, plus the legacy HTML, JSON, man-page formats etc. Existing consumers of those formats keep working during the transition, and contributors keep editing the same Markdown files they always have. +Under the hood, the beta is built with [doc-kit](https://github.com/nodejs/doc-kit), a standalone tool built to replace the current documentation generator, which has lived inside Node.js core for years. + +It parses the existing Markdown files and can produce several outputs from them: the redesigned web pages you see on the beta, plus the legacy HTML, JSON, man-page formats etc. Existing consumers of those formats keep working during the transition, and contributors keep editing the same Markdown files they always have. There's a broader goal here too: any project can pick up doc-kit for its own documentation, inside or outside the Node.js ecosystem. And that's already happening. The [undici docs](https://undici.nodejs.org/) are built with doc-kit today, and [webpack is migrating](https://github.com/webpack/webpack-doc-kit) its API documentation as well. @@ -35,3 +37,7 @@ If you're curious about the design and progress of the effort, the tracking issu This is a beta, and we're publishing it early because we want people using it and giving us feedback, so we can iterate before the new docs replace the current ones. If you spend time in the API docs, try spending it on [beta.docs.nodejs.org](https://beta.docs.nodejs.org/) for a while and let us know how it goes. Please open an issue on the [nodejs/doc-kit](https://github.com/nodejs/doc-kit/issues) repository with anything you find, big or small. The current documentation remains in place in the meantime, so nothing changes for you today — but with your help, the new docs will be ready to take over soon. + +## Acknowledgments + +None of this would exist without the [Node.js Web Team](https://github.com/nodejs/web-team/blob/main/MEMBERS.md), whose members designed, built, and reviewed everything described in this post. Thanks as well to the Node.js community and the collaborators who have already helped by reviewing, testing, and making suggestions along the way. Thank you all for making this possible. From 10593f1a08d38b7dd78cb489a68a613898c742c8 Mon Sep 17 00:00:00 2001 From: Brian Muenzenmeyer Date: Mon, 13 Jul 2026 15:37:11 -0500 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Brian Muenzenmeyer --- apps/site/pages/en/blog/announcements/new-api-docs-beta.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md index f07b362815068..36aa1c55aed0f 100644 --- a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md +++ b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md @@ -15,7 +15,7 @@ The content itself hasn't changed: every page is generated from the same Markdow The redesign goes deeper than visuals, though: navigation, layout, and readability were all reworked so that finding and understanding an API takes less effort. On top of that, the beta adds things the current docs have never had: - **Search**: For the first time, the API docs have built-in search. A search box on every page, with a keyboard shortcut, lets you jump anywhere in the API without a detour through a search engine. -- **One design across the project**: The API docs now shares the design system of the nodejs.org website, with a persistent sidebar listing every module, an always-visible per-page table of contents, and a layout that works on small screens. +- **One design across the project**: The API docs now share the design system of the nodejs.org website, with a persistent sidebar listing every module, an always-visible per-page table of contents, and a layout that works on small screens. - **Docs as Markdown**: Every page can now be viewed as plain Markdown, a format that AI tools like Claude Code and Codex can work with natively. Point them at a page and they can read it as is, with no HTML scraping in between. And that's not the whole list: the beta also ships features like reading times, announcement bars, [llms.txt](https://nodejs.org/llms.txt) etc. From 3c19d66e6b2daf87f6e337f76776a1bc688f0768 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= Date: Mon, 20 Jul 2026 16:55:32 -0300 Subject: [PATCH 4/8] fix: remove markdown from new features --- apps/site/pages/en/blog/announcements/new-api-docs-beta.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md index 36aa1c55aed0f..727c0a8a19716 100644 --- a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md +++ b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md @@ -10,13 +10,12 @@ We've been rebuilding how Node.js generates and presents its API documentation, ## What's different for readers -The content itself hasn't changed: every page is generated from the same Markdown files in the [nodejs/node](https://github.com/nodejs/node) repository that power the current docs. The features you rely on today made the trip too: light and dark themes, ESM/CJS switching and copy buttons on snippets, stability badges, and version history. +The content itself hasn't changed: every page is generated from the same Markdown files in the [nodejs/node](https://github.com/nodejs/node) repository that power the current docs. The features you rely on today made the trip too: light and dark themes, ESM/CJS switching and copy buttons on snippets, stability badges, version history, and the Markdown version of every page. The redesign goes deeper than visuals, though: navigation, layout, and readability were all reworked so that finding and understanding an API takes less effort. On top of that, the beta adds things the current docs have never had: - **Search**: For the first time, the API docs have built-in search. A search box on every page, with a keyboard shortcut, lets you jump anywhere in the API without a detour through a search engine. - **One design across the project**: The API docs now share the design system of the nodejs.org website, with a persistent sidebar listing every module, an always-visible per-page table of contents, and a layout that works on small screens. -- **Docs as Markdown**: Every page can now be viewed as plain Markdown, a format that AI tools like Claude Code and Codex can work with natively. Point them at a page and they can read it as is, with no HTML scraping in between. And that's not the whole list: the beta also ships features like reading times, announcement bars, [llms.txt](https://nodejs.org/llms.txt) etc. From 14aae4f2ed2259b25f192222dd693312946c4e24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= Date: Mon, 20 Jul 2026 17:40:25 -0300 Subject: [PATCH 5/8] fix: review --- .../en/blog/announcements/new-api-docs-beta.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md index 727c0a8a19716..264a2918c8447 100644 --- a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md +++ b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md @@ -1,7 +1,7 @@ --- date: '2026-07-12T12:00:00.000Z' category: announcements -title: Try the New Node.js API Documentation Beta +title: Check out the New Node.js API Documentation Preview layout: blog-post author: Guilherme Araújo --- @@ -17,25 +17,19 @@ The redesign goes deeper than visuals, though: navigation, layout, and readabili - **Search**: For the first time, the API docs have built-in search. A search box on every page, with a keyboard shortcut, lets you jump anywhere in the API without a detour through a search engine. - **One design across the project**: The API docs now share the design system of the nodejs.org website, with a persistent sidebar listing every module, an always-visible per-page table of contents, and a layout that works on small screens. -And that's not the whole list: the beta also ships features like reading times, announcement bars, [llms.txt](https://nodejs.org/llms.txt) etc. +And that's not the whole list: the beta also ships features like reading times and announcement bars. We also care about the needs of every user, and we pay attention to the ones that are easy to overlook. Every page stays usable even with JavaScript disabled and offline. -## Same content, new tooling +## Under-the-hood -Under the hood, the beta is built with [doc-kit](https://github.com/nodejs/doc-kit), a standalone tool built to replace the current documentation generator, which has lived inside Node.js core for years. +The redesigned documentation is built with [doc-kit](https://github.com/nodejs/doc-kit), a standalone tool developed by the Node.js Project to replace the previous, legacy, documentation generator. -It parses the existing Markdown files and can produce several outputs from them: the redesigned web pages you see on the beta, plus the legacy HTML, JSON, man-page formats etc. Existing consumers of those formats keep working during the transition, and contributors keep editing the same Markdown files they always have. - -There's a broader goal here too: any project can pick up doc-kit for its own documentation, inside or outside the Node.js ecosystem. And that's already happening. The [undici docs](https://undici.nodejs.org/) are built with doc-kit today, and [webpack is migrating](https://github.com/webpack/webpack-doc-kit) its API documentation as well. - -If you're curious about the design and progress of the effort, the tracking issue at [nodejs/node#52343](https://github.com/nodejs/node/issues/52343) has the full picture. +For more information on doc-kit, and its capabilities for other projects, please refer to [its repository](https://github.com/nodejs/doc-kit). This will also be the place where any and all bug reports, feature requests, and other tasks should be tracked. ## We need your feedback -This is a beta, and we're publishing it early because we want people using it and giving us feedback, so we can iterate before the new docs replace the current ones. If you spend time in the API docs, try spending it on [beta.docs.nodejs.org](https://beta.docs.nodejs.org/) for a while and let us know how it goes. - -Please open an issue on the [nodejs/doc-kit](https://github.com/nodejs/doc-kit/issues) repository with anything you find, big or small. The current documentation remains in place in the meantime, so nothing changes for you today — but with your help, the new docs will be ready to take over soon. +While we are proud to state that the redesigned documentation is entering its final stage of development, feedback is still a crucial part of this migration, and we'd love to hear your thoughts on this process. Please open an issue on the [nodejs/doc-kit](https://github.com/nodejs/doc-kit/issues) repository with anything you find, big or small. ## Acknowledgments From 23de560c4a63bad7535d287f1dca8e5a84012260 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= Date: Mon, 20 Jul 2026 17:54:06 -0300 Subject: [PATCH 6/8] feat: add llms.txt point --- apps/site/pages/en/blog/announcements/new-api-docs-beta.md | 1 + 1 file changed, 1 insertion(+) diff --git a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md index 264a2918c8447..9917228b868b1 100644 --- a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md +++ b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md @@ -16,6 +16,7 @@ The redesign goes deeper than visuals, though: navigation, layout, and readabili - **Search**: For the first time, the API docs have built-in search. A search box on every page, with a keyboard shortcut, lets you jump anywhere in the API without a detour through a search engine. - **One design across the project**: The API docs now share the design system of the nodejs.org website, with a persistent sidebar listing every module, an always-visible per-page table of contents, and a layout that works on small screens. +- **llms.txt**: We've already shipped [llms.txt](https://nodejs.org/llms.txt), giving AI tools a clean, structured entry point to the API reference. And that's not the whole list: the beta also ships features like reading times and announcement bars. From f3c01ac19ec861346ba480a35b428f21700c7619 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= Date: Fri, 24 Jul 2026 16:17:37 -0300 Subject: [PATCH 7/8] Potential fix for pull request finding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Guilherme Araújo --- apps/site/pages/en/blog/announcements/new-api-docs-beta.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md index 9917228b868b1..f6b810940e132 100644 --- a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md +++ b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md @@ -24,9 +24,9 @@ We also care about the needs of every user, and we pay attention to the ones tha ## Under-the-hood -The redesigned documentation is built with [doc-kit](https://github.com/nodejs/doc-kit), a standalone tool developed by the Node.js Project to replace the previous, legacy, documentation generator. +The redesigned documentation is built with [doc-kit](https://github.com/nodejs/doc-kit), a standalone tool developed by the Node.js Project to replace the previous legacy documentation generator. -For more information on doc-kit, and its capabilities for other projects, please refer to [its repository](https://github.com/nodejs/doc-kit). This will also be the place where any and all bug reports, feature requests, and other tasks should be tracked. +For more information on doc-kit and its capabilities for other projects, please refer to [its repository](https://github.com/nodejs/doc-kit). This will also be the place where bug reports, feature requests, and other tasks should be tracked. ## We need your feedback From 81f30d802b1e406e39f0d3da26aacb29d585f942 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= Date: Fri, 24 Jul 2026 16:24:55 -0300 Subject: [PATCH 8/8] chore: update post datetime --- apps/site/pages/en/blog/announcements/new-api-docs-beta.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md index f6b810940e132..bf8f6fc4fc3d6 100644 --- a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md +++ b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md @@ -1,5 +1,5 @@ --- -date: '2026-07-12T12:00:00.000Z' +date: '2026-07-24T19:00:00.000Z' category: announcements title: Check out the New Node.js API Documentation Preview layout: blog-post