Skip to content

Commit f293f9e

Browse files
committed
fix: review
1 parent 82e7259 commit f293f9e

1 file changed

Lines changed: 7 additions & 21 deletions

File tree

‎apps/site/pages/en/blog/announcements/new-api-docs-beta.md‎

Lines changed: 7 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
date: '2026-07-12T12:00:00.000Z'
33
category: announcements
4-
title: Try the New Node.js API Documentation Beta
4+
title: Check out the Node.js API Documentation Redesign Preview
55
layout: blog-post
66
author: Guilherme Araújo
77
---
@@ -10,33 +10,19 @@ We've been rebuilding how Node.js generates and presents its API documentation,
1010

1111
## What's different for readers
1212

13-
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.
13+
Like the current documentation, every page is generated from the same Markdown files in the [nodejs/node](https://github.com/nodejs/node) repository that power the current docs. However, 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, including offline-compatible search, an `llms.txt` file, and a modern overhaul of the visual identity to match the rest of the Node.js brand.
1414

15-
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:
15+
## Under-the-hood
1616

17-
- **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.
18-
- **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.
19-
- **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.
17+
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.
2018

21-
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.
22-
23-
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.
24-
25-
## Same content, new tooling
26-
27-
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.
28-
29-
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.
30-
31-
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.
32-
33-
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.
19+
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.
3420

3521
## We need your feedback
3622

37-
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.
23+
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.
3824

39-
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.
25+
One important note: `beta.docs.nodejs.org` is a temporary address for this preview and will go away once the redesign becomes the default documentation. Please don't link to it from your own blog posts, tutorials, or other resources.
4026

4127
## Acknowledgments
4228

0 commit comments

Comments
 (0)