doc: move to redesign by avivkeller · Pull Request #66713 · nodejs/node

avivkeller · 2026-10-13T21:43:59Z

This PR shouldn't change much from it's current form. Most changes will go in doc-kit. test-make-doc was removed, since our new generator minifies the output HTML (so it's format is structurally inconsistent) and can't be easily parsed with the existing regular expressions.

Furthermore, such tests are not needed due to our tests in doc-kit.

Preview: https://beta.docs.nodejs.org

Notable Change:

Node.js is thrilled to announce a brand new redesign of our documentation experience! The updated documentation now features HTML structure and styling that are much more closely aligned with the main Node.js website UI, creating a more consistent experience across the brand. You can check out the redesigned documentation today at ~~https://nodejs.org/api~~ (Striked out since this isn't correct until this PR lands).

nodejs-github-bot · 2026-10-13T21:44:04Z

Review requested:

@nodejs/web-infra

bmuenzenmeyer

I think we need to do better, align on fallback strategy here, or at least affirm that #66613 or this test is enough (not both) . If canBundle ever returns false, we don't get HTML docs at all, which we identified as a production issue worthy of an expensive new release.

Could we add this check to the release process too? Is CI enough? Perhaps

codecov · 2026-10-13T23:22:55Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.68%. Comparing base (d44625a) to head (62a50c5).
⚠️ Report is 24 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #66713      +/-   ##
==========================================
- Coverage   90.69%   90.68%   -0.02%     
==========================================
  Files         797      797              
  Lines      278787   278874      +87     
  Branches    53607    53626      +19     
==========================================
+ Hits       252858   252908      +50     
- Misses      16292    16325      +33     
- Partials     9637     9641       +4

see 41 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

avivkeller · 2026-10-14T14:30:10Z

If canBundle ever returns false, we don't get HTML docs at all, which we identified as a production issue worthy of an expensive new release.

We know that lightningcss resolves on release machines, so I assume Rolldown will as well, but I 100% want to double-check that on a release-ci after regular CI passes (a regular CI is not enough).

nodejs-github-bot · 2026-10-19T15:28:56Z

CI: https://ci.nodejs.org/job/node-test-pull-request/78489/

nodejs-github-bot · 2026-10-19T15:32:41Z

CI: https://ci.nodejs.org/job/node-test-pull-request/78490/

nodejs-github-bot · 2026-10-20T08:51:17Z

CI: https://ci.nodejs.org/job/node-test-pull-request/78498/

nodejs-github-bot · 2026-10-20T08:51:25Z

CI: https://ci.nodejs.org/job/node-test-pull-request/78499/

Co-authored-by: Brian Muenzenmeyer <brian.muenzenmeyer@gmail.com> Signed-off-by: avivkeller <me@aviv.sh>

Pass `skip_apidoc_files` from the Makefile to doc-kit with `--ignore` instead of duplicating the list in the config file, and read the list in test-make-doc.mjs synchronously (the callback `fs.open` was being awaited, which threw ERR_INVALID_ARG_TYPE). Assisted-by: Claude Fable 5.1

ovflowd

SgTm (Sorcerer Got Temu Merchandise)

nodejs-github-bot · 2026-10-31T17:14:19Z

CI: https://ci.nodejs.org/job/node-test-pull-request/78771/

Generate llms.txt from the web config instead of a separate doc-kit call with `-t llms-txt`. The single call already passes the config, so `llms-txt` joins its targets, with its output pinned to out/doc where it lived before, and out/doc/llms.txt becomes one more output of the stamp rule. The outputs are now listed once, in apidoc_outputs, and the comment above them says what the stamp is for. The built docs are identical to before, llms.txt included. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

bmuenzenmeyer

LGTM

nodejs-github-bot · 2026-11-02T00:55:17Z

CI: https://ci.nodejs.org/job/node-test-pull-request/78784/

Quote the config's top-level keys: 'llms-txt' needs quotes, and the quote-props rule wants the other keys at that level quoted to match. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

avivkeller · 2026-11-02T18:15:31Z

Adding to the TSC agenda for visibility that this is ready, so they can give their input

nodejs-github-bot added build Issues and PRs related to Node.js builds or CI infrastructure. doc Issues and PRs related to Node.js documentation. needs-ci PRs that need a full CI run. tools Issues and PRs related to the tools directory. labels Oct 13, 2026

ovflowd reviewed Oct 13, 2026

View reviewed changes

Comment thread tools/doc/web.doc-kit.config.mjs Resolved

bmuenzenmeyer requested changes Oct 13, 2026

View reviewed changes

Comment thread test/doctool/test-make-doc.mjs Resolved

Comment thread test/doctool/test-make-doc.mjs Resolved

avivkeller requested a review from bmuenzenmeyer October 15, 2026 14:28

ovflowd reviewed Oct 15, 2026

View reviewed changes

Comment thread tools/doc/web.doc-kit.config.mjs Resolved

ovflowd mentioned this pull request Oct 26, 2026

rhel8-x64 executors in the CI frequently to have an unexpected 25 minute "pause" around the doc gen execution pase nodejs/doc-kit#1174

Closed

ovflowd force-pushed the redesign branch from dbfdf8d to 71a9e69 Compare October 26, 2026 21:47

bmuenzenmeyer reviewed Oct 27, 2026

View reviewed changes

Comment thread test/doctool/test-make-doc.mjs Resolved

Comment thread tools/doc/web.doc-kit.config.mjs Resolved

build, doc: move to redesign

443279c

Co-authored-by: Brian Muenzenmeyer <brian.muenzenmeyer@gmail.com> Signed-off-by: avivkeller <me@aviv.sh>

avivkeller force-pushed the redesign branch from c9921fa to 443279c Compare October 31, 2026 13:28

fixup!

2b71e96

This comment was marked as outdated.

Sign in to view

avivkeller added 2 commits October 31, 2026 14:53

fixup!

3e3ea73

ovflowd mentioned this pull request Oct 31, 2026

perf: stream dependencies between generators nodejs/doc-kit#1205

Open

4 tasks done

richardlau reviewed Oct 31, 2026

View reviewed changes

Comment thread test/doctool/test-docs.mjs Resolved

ovflowd approved these changes Oct 31, 2026

View reviewed changes

avivkeller added the author ready PRs with CI started, the required approvals, and no outstanding review comments. label Oct 31, 2026

avivkeller requested a review from bmuenzenmeyer October 31, 2026 21:40

ovflowd mentioned this pull request Oct 31, 2026

tools: bump @node-core/doc-kit from 1.4.1 to 2.0.6 in /tools/doc in the doc group across 1 directory #67022

Closed

bmuenzenmeyer reviewed Nov 1, 2026

View reviewed changes

Comment thread Makefile Resolved

Comment thread Makefile Resolved

Comment thread tools/doc/web.doc-kit.config.mjs Resolved

ovflowd added the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Nov 1, 2026

ovflowd requested a review from bmuenzenmeyer November 1, 2026 23:07

bmuenzenmeyer approved these changes Nov 2, 2026

View reviewed changes

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Nov 2, 2026

fixup! build, doc: move to redesign

62a50c5

Quote the config's top-level keys: 'llms-txt' needs quotes, and the quote-props rule wants the other keys at that level quoted to match. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

AugustinMauroy approved these changes Nov 2, 2026

View reviewed changes

ovflowd added the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Nov 2, 2026

ovflowd approved these changes Nov 2, 2026

View reviewed changes

avivkeller added the tsc-agenda Issues and PRs to discuss during Technical Steering Committee meetings. label Nov 2, 2026

avivkeller removed the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Nov 2, 2026

Conversation

avivkeller commented Oct 13, 2026

Uh oh!

nodejs-github-bot commented Oct 13, 2026

Uh oh!

Uh oh!

bmuenzenmeyer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

avivkeller commented Oct 14, 2026

Uh oh!

Uh oh!

nodejs-github-bot commented Oct 19, 2026

Uh oh!

nodejs-github-bot commented Oct 19, 2026

Uh oh!

nodejs-github-bot commented Oct 20, 2026

Uh oh!

nodejs-github-bot commented Oct 20, 2026

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

ovflowd left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Oct 31, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bmuenzenmeyer left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Nov 2, 2026

Uh oh!

avivkeller commented Nov 2, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codecov Bot commented Oct 13, 2026 •

edited

Loading