chore(blog): announce documentation redesign - #9167
Draft
avivkeller wants to merge 2 commits into
Draft
avivkeller wants to merge 2 commits into
avivkeller wants to merge 2 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #9167 +/- ##
==========================================
+ Coverage 86.08% 86.10% +0.01%
==========================================
Files 86 86
Lines 6046 6040 -6
Branches 357 357
==========================================
- Hits 5205 5201 -4
+ Misses 837 835 -2
Partials 4 4 ☔ View full report in Codecov by Harness. |
avivkeller
commented
Sep 21, 2026
Signed-off-by: Aviv Keller <me@aviv.sh>
Contributor
📦 Build Size ComparisonSummary
Changes🔄 Modified Routes (4)
|
bmuenzenmeyer
left a comment
bmuenzenmeyer
left a comment
Contributor
There was a problem hiding this comment.
I know this is draft but thought I'd add some initial thoughts.
I don't know if this voice is exactly what I would choose (things like we love you, but I refrained from flagging too much of it. This is your blog post and you are right to state you had the largest hand in making it a reality.
Comment on lines
+9
to
+11
| A few years ago, [nodejs.org](https://nodejs.org) went through an [extensive makeover](https://nodejs.org/en/blog/announcements/diving-into-the-nodejs-website-redesign). Since then, we have done anything and everything but slow down. | ||
|
|
||
| For the past few years, the Node.js Web Team has been hard at work creating a brand-new documentation design system to complement the overhaul of [nodejs.org](https://nodejs.org). |
Contributor
There was a problem hiding this comment.
nit: this feels like two intros. Combine
|
|
||
| ## How We Got Here | ||
|
|
||
| Like the [website](https://nodejs.org/en/blog/announcements/diving-into-the-nodejs-website-redesign), we've taken great care in approaching and implementing this design. As the saying goes, "Rome wasn't built in a day," and it's important that we highlight the often thankless work of the maintainers who made this redesign what it is today. |
Contributor
There was a problem hiding this comment.
suggest omitting this blog a second time (and later a third)
Suggested change
| Like the [website](https://nodejs.org/en/blog/announcements/diving-into-the-nodejs-website-redesign), we've taken great care in approaching and implementing this design. As the saying goes, "Rome wasn't built in a day," and it's important that we highlight the often thankless work of the maintainers who made this redesign what it is today. | |
| Like the website, we've taken great care in approaching and implementing this design. As the saying goes, "Rome wasn't built in a day," and it's important that we highlight the often thankless work of the maintainers who made this redesign what it is today. |
| * A mobile interface | ||
| * A sticky sidebar with reading time, historical information, and a table of contents. | ||
|
|
||
| ## How We Got Here |
Contributor
There was a problem hiding this comment.
I think this could be better explained with some of the content from the doc-kit talk, where we work through the timeline of constraints and consensus at the outset, ever-expanding feedback loops, like-for-like experience first, beta, etc.
|
|
||
| This was largely due to a few key issues: | ||
|
|
||
| 1. There was no [first-party way to search](https://github.com/nodejs/node/issues/31598) the API documentation, and external search engines could provide [contradictory or mismatched information](https://github.com/nodejs/nodejs.org/issues/6577). |
|
|
||
| ### Working Backwards | ||
|
|
||
| Unless you have brainpower far exceeding the entirety of humankind, there is no practical way to "visualize" an abstract syntax tree. |
Contributor
There was a problem hiding this comment.
This is sorta odd of a statement. You might be better off actually showing a short AST for something like
console.log(`hello {name}`)
|
|
||
| Once we had that foundation, the next step was the two-month-long PR adding the [`web` generator](https://github.com/nodejs/doc-kit/pull/285), responsible for taking the generated JSX, bundling the required components and JavaScript, and producing the redesigned static documentation pages. | ||
|
|
||
| ### Refining |
Contributor
There was a problem hiding this comment.
I think this could be better explained with some of the content from the doc-kit talk, where we talk of ever-expanding feedback loops.
|
|
||
| ### The Redesigned JSON Generator | ||
|
|
||
| A [redesigned JSON generator](https://github.com/nodejs/doc-kit/pull/1079) would allow us to create a more deliberate, documented, and extensible representation of the Node.js API, particularly one that allows consumers to easily parse Node.js types, descriptions, and other details. We plan to work closely with the [`@types/node` maintainers](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node) to create a JSON format that allows consumers to learn all the same information available visually, in a more machine-readable format. |
Contributor
There was a problem hiding this comment.
IIRC, the types/node folks didn't seem to care too much about this.
araujogui
reviewed
Sep 22, 2026
|
|
||
| ## Thanks | ||
|
|
||
| If I could, I would list the name of [each and every person who's contributed to `doc-kit`](https://github.com/nodejs/doc-kit/graphs/contributors) (including you, by reading this article). In an effort to keep you awake, I'll shorten that list to a few people and teams of note. |
Member
There was a problem hiding this comment.
Suggested change
| If I could, I would list the name of [each and every person who's contributed to `doc-kit`](https://github.com/nodejs/doc-kit/graphs/contributors) (including you, by reading this article). In an effort to keep you awake, I'll shorten that list to a few people and teams of note. | |
| If I could, I would list the name of [each and every person who's contributed to `doc-kit`](https://github.com/nodejs/doc-kit/graphs/contributors?all=1) (including you, by reading this article). In an effort to keep you awake, I'll shorten that list to a few people and teams of note. |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
(Blocked by the release of Node.js v26.10.0)
https://nodejs-org-git-doc-redesign-openjs.vercel.app/en/blog/announcements/new-docs-site