Skip to content

refactor: move all.html into a Node.js generator - #1242

Open
ovflowd wants to merge 4 commits into
perf/stream-htmlfrom
refactor/html-all
Open

ovflowd wants to merge 4 commits into
perf/stream-htmlfrom
refactor/html-all

Conversation

@ovflowd

@ovflowd ovflowd commented Nov 3, 2026 •

Copy link
Copy Markdown
Member

Description

This PR moves all.html out of html and into html-all, a new generator in @node-core/doc-kit: it's Node.js's page, so doc-kit itself shouldn't need to know about it. It's part of the stack that splits #1205.

  • html-all is spliced between jsx-ast and html. It adds all.html's metadata to the manifest and, right after the last module page, all.html itself as a composed page of them, in the manifest's order.
  • html renders a composed page (an item with parts) from its parts' compiled content, one part at a time. The worker rendering all.html went from 330-388MB to 176-189MB.
  • generateAllPage is removed, which is a breaking change for @doc-kit/generator-react. Builds that want all.html add -t html-all, as CI's e2e build now does. Node.js's config needs it too (doc: move to redesign node#66713).

Validation

Added tests for html-all (all.html right after its last part, and after every page given at once, as with one thread), and for html assembling a composed page from its parts. With -t html-all, the output on 12 of Node.js's API docs is byte-identical to main's, all.html included, at 1 and 4 threads.

Related Issues

Refs: #1205

Check List

  • I have read the Contributing Guidelines and made commit messages that follow the guideline.
  • I have run node --run test and all tests passed.
  • I have check code formatting with node --run format:check & node --run lint.
  • I've covered new added functionality with unit tests if necessary.

@vercel

vercel Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
api-docs-tooling Ready Ready Preview Nov 20, 2026 9:46pm UTC

Request Review

@ovflowd
ovflowd added this pull request to stack #1244 November 3, 2026 19:34
@codecov

codecov Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.02%. Comparing base (d39a4ae) to head (6161190).

Additional details and impacted files
@@                 Coverage Diff                  @@
##           perf/stream-html    #1242      +/-   ##
====================================================
+ Coverage             93.99%   94.02%   +0.03%     
====================================================
  Files                   298      300       +2     
  Lines                 31477    31653     +176     
  Branches               3205     3219      +14     
====================================================
+ Hits                  29586    29763     +177     
+ Misses                 1869     1868       -1     
  Partials                 22       22              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 6161190 2026-11-20T21:46:41.225Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 89a3322 2026-11-18T03:38:50.058Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ f64aca9 2026-11-17T14:45:11.643Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 16acb7e 2026-11-13T16:49:45.010Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 78217c5 2026-11-11T00:07:44.987Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 71861b9 2026-11-10T20:53:54.997Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 54e59de 2026-11-09T13:26:23.994Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ a8bfd7f 2026-11-09T11:04:20.654Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 822cbaf 2026-11-09T10:38:12.588Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 0931ca2 2026-11-09T02:27:17.176Z View logs ↗

View all previews: View all previews ↗

all.html, every module page's content on one page, is Node.js's, but
html built it in, behind generateAllPage, and the streaming work spread
its bookkeeping through generate.mjs.

It's now a generator of @node-core/doc-kit, html-all, spliced between
jsx-ast and html the way section-pages is between metadata and jsx-ast.
It passes the pages on, adds all.html's metadata to the manifest, and
right after the last module page adds all.html as a page made of
theirs, in sidebar order. html only knows that an item with parts, the
pages before it that it's made of, is compiled from their content and
rendered first, one part at a time instead of building every part's
elements before rendering any; generateAllPage goes away. Built with
the Node.js preset and the html-all target, the Node.js API docs come
out byte-identical, all.html included, at 1 and 4 threads.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Assisted-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…t lives

The code and types already called it a composed page, while the docs,
comments and tests said a page made of other pages. They all say
composed page now.

html-all no longer adds all.html at the end when no manifest came, as
jsx-ast always sends one, and each page it lists arrives. html's test
of the bundles' timing no longer gives it all.html, whose place
html-all's tests check, the composed page's program test only checks
what it imports, as html's tests render one, and html's tests build
all.html's metadata with createSyntheticHead.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
As jsx-ast and html, html-all always gets an async iterable now, so it
drops toBatches and takes only that type. Its test gives the one-thread
input with once, and reads the output with Array.fromAsync.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Since the layer below, jsx-ast's manifest lists the pages in the order
the site does, so html-all takes all.html's parts in that order instead
of sorting them with headingSortFn, which the react package no longer
exports.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
Preview – api-docs-tooling — 61611909 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants