feat(web): add all, index, and 404 generation by avivkeller · Pull Request #780 · nodejs/doc-kit

avivkeller · 2026-04-29T20:43:56Z

Closes #622
Closes #644
Closes #357

vercel · 2026-04-29T20:44:02Z

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	May 4, 2026 8:40pm

cursor · 2026-04-29T20:44:02Z

PR Summary

Medium Risk
Adds new synthetic page generation and changes how web bundles entries/sidebars in a single pass, which could affect navigation, output file sets, and build performance. Also relies on jsx-ast now attaching sectionEntries, so downstream compatibility depends on that new field.

Overview
The web generator now optionally emits synthetic all.html, index.html (with a stability overview table), and 404.html, controlled by new config flags (generateAllPage, generateIndexPage, generateNotFoundPage, defaulting to true).

To support this, jsx-ast now preserves each module’s raw section metadata on the generated content (sectionEntries), and web reconstructs metadata to build synthetic entries via new helpers in utils/synthetic/*, while keeping the sidebar page list limited to real module pages. processJSXEntries now accepts an explicit sidebarEntries list, and the web generator’s return type was updated to a non-streaming Promise.

^{Reviewed by Cursor Bugbot for commit 468b6ce. Bugbot is set up for automated code reviews on this repo. Configure here.}

codecov · 2026-04-29T20:44:47Z

Codecov Report

❌ Patch coverage is 84.41558% with 72 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.19%. Comparing base (05f0e64) to head (468b6ce).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/generators/web/generate.mjs	0.00%	49 Missing ⚠️
src/generators/web/utils/synthetic/index.mjs	85.00%	12 Missing ⚠️
src/generators/jsx-ast/generate.mjs	0.00%	5 Missing ⚠️
src/generators/web/utils/processing.mjs	28.57%	5 Missing ⚠️
...ators/web/utils/synthetic/__tests__/index.test.mjs	98.83%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #780      +/-   ##
==========================================
+ Coverage   77.95%   78.19%   +0.24%     
==========================================
  Files         159      167       +8     
  Lines       14056    14510     +454     
  Branches     1152     1192      +40     
==========================================
+ Hits        10957    11346     +389     
- Misses       3094     3159      +65     
  Partials        5        5

☔ View full report in Codecov by Sentry.
📢 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.

github-actions · 2026-04-29T20:46:10Z

`orama-db` Generator

File	Base	Head	Diff
`orama-db.json`	8.38 MB	8.38 MB	+1.24 KB (+0.01%)

`web` Generator

File	Base	Head	Diff
`index.js`	5.79 KB	13.54 KB	+7.75 KB (+133.67%)
`index.html`	36.49 KB	42.50 KB	+6.02 KB (+16.50%)
`addons.html`	262.77 KB	262.56 KB	-212.00 B (-0.08%)
`assert.html`	330.24 KB	330.03 KB	-212.00 B (-0.06%)
`async_context.html`	187.81 KB	187.60 KB	-212.00 B (-0.11%)
`async_hooks.html`	159.95 KB	159.74 KB	-212.00 B (-0.13%)
`buffer.html`	908.46 KB	908.26 KB	-212.00 B (-0.02%)
`child_process.html`	381.93 KB	381.72 KB	-212.00 B (-0.05%)
`cli.html`	502.41 KB	502.20 KB	-212.00 B (-0.04%)
`cluster.html`	196.53 KB	196.33 KB	-212.00 B (-0.11%)
`console.html`	147.01 KB	146.80 KB	-212.00 B (-0.14%)
`crypto.html`	1.09 MB	1.09 MB	-212.00 B (-0.02%)
`debugger.html`	66.58 KB	66.37 KB	-212.00 B (-0.31%)
`deprecations.html`	505.66 KB	505.45 KB	-212.00 B (-0.04%)
`dgram.html`	194.60 KB	194.39 KB	-212.00 B (-0.11%)
`diagnostics_channel.html`	303.69 KB	303.49 KB	-212.00 B (-0.07%)
`dns.html`	297.35 KB	297.14 KB	-212.00 B (-0.07%)
`documentation.html`	38.25 KB	38.04 KB	-212.00 B (-0.54%)
`domain.html`	105.34 KB	105.13 KB	-212.00 B (-0.20%)
`embedding.html`	59.63 KB	59.43 KB	-212.00 B (-0.35%)
`environment_variables.html`	44.25 KB	44.04 KB	-212.00 B (-0.47%)
`errors.html`	464.86 KB	464.66 KB	-212.00 B (-0.04%)
`esm.html`	155.55 KB	155.34 KB	-212.00 B (-0.13%)
`events.html`	455.50 KB	455.29 KB	-212.00 B (-0.05%)
`ffi.html`	126.67 KB	126.47 KB	-212.00 B (-0.16%)
`fs.html`	1.43 MB	1.43 MB	-212.00 B (-0.01%)
`globals.html`	230.59 KB	230.39 KB	-212.00 B (-0.09%)
`http.html`	746.40 KB	746.19 KB	-212.00 B (-0.03%)
`http2.html`	768.90 KB	768.70 KB	-212.00 B (-0.03%)
`https.html`	150.58 KB	150.38 KB	-212.00 B (-0.14%)
`inspector.html`	171.64 KB	171.44 KB	-212.00 B (-0.12%)
`intl.html`	58.35 KB	58.14 KB	-212.00 B (-0.35%)
`module.html`	326.99 KB	326.78 KB	-212.00 B (-0.06%)
`modules.html`	178.88 KB	178.67 KB	-212.00 B (-0.12%)
`n-api.html`	811.52 KB	811.31 KB	-212.00 B (-0.03%)
`net.html`	382.62 KB	382.42 KB	-212.00 B (-0.05%)
`os.html`	142.96 KB	142.75 KB	-212.00 B (-0.14%)
`packages.html`	154.86 KB	154.65 KB	-212.00 B (-0.13%)
`path.html`	139.49 KB	139.29 KB	-212.00 B (-0.15%)
`perf_hooks.html`	381.73 KB	381.52 KB	-212.00 B (-0.05%)
`permissions.html`	57.56 KB	57.35 KB	-212.00 B (-0.36%)
`process.html`	676.45 KB	676.24 KB	-212.00 B (-0.03%)
`punycode.html`	63.43 KB	63.22 KB	-212.00 B (-0.33%)
`querystring.html`	64.09 KB	63.88 KB	-212.00 B (-0.32%)
`quic.html`	375.45 KB	375.24 KB	-212.00 B (-0.06%)
`readline.html`	252.41 KB	252.20 KB	-212.00 B (-0.08%)
`repl.html`	183.57 KB	183.36 KB	-212.00 B (-0.11%)
`report.html`	176.13 KB	175.92 KB	-212.00 B (-0.12%)
`single-executable-applications.html`	107.20 KB	106.99 KB	-212.00 B (-0.19%)
`sqlite.html`	284.78 KB	284.57 KB	-212.00 B (-0.07%)
`stream.html`	863.48 KB	863.27 KB	-212.00 B (-0.02%)
`stream_iter.html`	352.62 KB	352.41 KB	-212.00 B (-0.06%)
`string_decoder.html`	55.63 KB	55.42 KB	-212.00 B (-0.37%)
`synopsis.html`	42.88 KB	42.67 KB	-212.00 B (-0.48%)
`test.html`	786.85 KB	786.64 KB	-212.00 B (-0.03%)
`timers.html`	133.74 KB	133.53 KB	-212.00 B (-0.15%)
`tls.html`	374.02 KB	373.82 KB	-212.00 B (-0.06%)
`tracing.html`	84.39 KB	84.18 KB	-212.00 B (-0.25%)
`tty.html`	95.53 KB	95.32 KB	-212.00 B (-0.22%)
`typescript.html`	53.68 KB	53.47 KB	-212.00 B (-0.39%)
`url.html`	347.91 KB	347.70 KB	-212.00 B (-0.06%)
`util.html`	696.01 KB	695.80 KB	-212.00 B (-0.03%)
`v8.html`	339.33 KB	339.13 KB	-212.00 B (-0.06%)
`vm.html`	371.03 KB	370.83 KB	-212.00 B (-0.06%)
`wasi.html`	69.60 KB	69.40 KB	-212.00 B (-0.30%)
`webcrypto.html`	522.92 KB	522.71 KB	-212.00 B (-0.04%)
`webstreams.html`	357.42 KB	357.21 KB	-212.00 B (-0.06%)
`worker_threads.html`	370.83 KB	370.63 KB	-212.00 B (-0.06%)
`zlib.html`	290.48 KB	290.27 KB	-212.00 B (-0.07%)
`zlib_iter.html`	88.30 KB	88.09 KB	-212.00 B (-0.23%)
`addons.js`	288.81 KB	288.81 KB	-5.00 B (-0.00%)
`assert.js`	448.96 KB	448.97 KB	+5.00 B (+0.00%)
`async_context.js`	213.42 KB	213.43 KB	+5.00 B (+0.00%)
`async_hooks.js`	191.51 KB	191.51 KB	+5.00 B (+0.00%)
`buffer.js`	1.08 MB	1.08 MB	+5.00 B (+0.00%)
`child_process.js`	457.77 KB	457.77 KB	+5.00 B (+0.00%)
`cli.js`	303.29 KB	303.29 KB	+5.00 B (+0.00%)
`cluster.js`	190.22 KB	190.23 KB	+5.00 B (+0.00%)
`console.js`	101.69 KB	101.70 KB	+5.00 B (+0.00%)
`crypto.js`	1.21 MB	1.21 MB	+5.00 B (+0.00%)
`debugger.js`	48.56 KB	48.56 KB	-5.00 B (-0.01%)
`deprecations.js`	285.61 KB	285.61 KB	-5.00 B (-0.00%)
`dgram.js`	165.66 KB	165.67 KB	+5.00 B (+0.00%)
`diagnostics_channel.js`	302.75 KB	302.75 KB	+5.00 B (+0.00%)
`dns.js`	259.62 KB	259.63 KB	+5.00 B (+0.00%)
`domain.js`	85.64 KB	85.64 KB	+5.00 B (+0.01%)
`environment_variables.js`	11.70 KB	11.70 KB	-5.00 B (-0.04%)
`errors.js`	349.41 KB	349.40 KB	-5.00 B (-0.00%)
`esm.js`	131.43 KB	131.44 KB	+5.00 B (+0.00%)
`events.js`	539.31 KB	539.31 KB	+5.00 B (+0.00%)
`ffi.js`	88.35 KB	88.36 KB	+5.00 B (+0.01%)
`fs.js`	1.22 MB	1.22 MB	+5.00 B (+0.00%)
`globals.js`	122.74 KB	122.75 KB	+5.00 B (+0.00%)
`http2.js`	796.06 KB	796.06 KB	+5.00 B (+0.00%)
`module.js`	330.80 KB	330.80 KB	+5.00 B (+0.00%)
`modules.js`	143.97 KB	143.97 KB	+5.00 B (+0.00%)
`n-api.js`	710.45 KB	710.45 KB	-5.00 B (-0.00%)
`net.js`	271.31 KB	271.32 KB	+5.00 B (+0.00%)
`os.js`	100.52 KB	100.52 KB	+5.00 B (+0.00%)
`packages.js`	118.89 KB	118.89 KB	-5.00 B (-0.00%)
`path.js`	91.91 KB	91.92 KB	+5.00 B (+0.01%)
`perf_hooks.js`	355.10 KB	355.10 KB	+5.00 B (+0.00%)
`permissions.js`	28.21 KB	28.20 KB	-5.00 B (-0.02%)
`process.js`	698.88 KB	698.88 KB	+5.00 B (+0.00%)
`punycode.js`	23.36 KB	23.37 KB	+5.00 B (+0.02%)
`querystring.js`	26.13 KB	26.14 KB	+5.00 B (+0.02%)
`quic.js`	164.35 KB	164.36 KB	+5.00 B (+0.00%)
`readline.js`	217.30 KB	217.31 KB	+5.00 B (+0.00%)
`repl.js`	205.02 KB	205.03 KB	+5.00 B (+0.00%)
`single-executable-applications.js`	80.14 KB	80.15 KB	+5.00 B (+0.01%)
`stream.js`	855.88 KB	855.88 KB	+5.00 B (+0.00%)
`stream_iter.js`	448.32 KB	448.32 KB	+5.00 B (+0.00%)
`string_decoder.js`	26.62 KB	26.63 KB	+5.00 B (+0.02%)
`timers.js`	93.29 KB	93.30 KB	+5.00 B (+0.01%)
`tls.js`	308.18 KB	308.19 KB	+5.00 B (+0.00%)
`tracing.js`	73.02 KB	73.02 KB	+5.00 B (+0.01%)
`tty.js`	42.95 KB	42.95 KB	+5.00 B (+0.01%)
`url.js`	330.67 KB	330.67 KB	+5.00 B (+0.00%)
`util.js`	741.35 KB	741.36 KB	+5.00 B (+0.00%)
`v8.js`	342.62 KB	342.62 KB	+5.00 B (+0.00%)
`wasi.js`	38.02 KB	38.03 KB	+5.00 B (+0.01%)
`webcrypto.js`	386.56 KB	386.56 KB	-5.00 B (-0.00%)
`webstreams.js`	280.03 KB	280.04 KB	+5.00 B (+0.00%)
`worker_threads.js`	400.12 KB	400.12 KB	+5.00 B (+0.00%)
`zlib.js`	307.44 KB	307.45 KB	+5.00 B (+0.00%)

AugustinMauroy · 2026-04-30T07:47:03Z

There are still stability overview heading in the about doc page. IMO there are 2 options

also include it there
remove this header by processing it. and in future remove the md content then remove the logic on generator

AugustinMauroy · 2026-04-30T07:47:23Z

BTW thanks aviv for your energy there !

avivkeller · 2026-04-30T22:10:21Z

remove this header by processing it. and in future remove the md content then remove the logic on generator

I think when we move to the web generator, we'll just remove the heading from the source

AugustinMauroy · 2026-05-01T07:28:13Z

remove this header by processing it. and in future remove the md content then remove the logic on generator

I think when we move to the web generator, we'll just remove the heading from the source

Agree make sens. But why not remove/merge index and about ? but for backward compatibility we can just duplicate the file with different name like index became the main thing and about became the copy.

avivkeller · 2026-05-02T19:06:10Z

@nodejs/web-infra Thoughts?

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 468b6ce. Configure here.}

cursor · 2026-05-04T20:44:12Z

+  //
+  // TODO(@avivkeller): Once this lands in core, remove the `index.html`
+  // page from Core, then remove this check.
+  const moduleEntries = input.filter(entry => entry.data.api !== 'index');


Index entry unconditionally removed regardless of config

Medium Severity

The filter input.filter(entry => entry.data.api !== 'index') unconditionally removes Core's index entry from the pipeline. However, the synthetic replacement index page is only generated when config.generateIndexPage is true. If a user sets generateIndexPage: false, the Core index entry is still removed but no replacement is created, resulting in no index.html in the output at all. The comment even states this replacement happens "when generateIndexPage is on", but the filtering isn't gated by that condition.

^{Reviewed by Cursor Bugbot for commit 468b6ce. Configure here.}

AugustinMauroy

LGMT !

AugustinMauroy · 2026-05-05T07:39:54Z

+ *
+ * @param {Array<import('../../../metadata/types').MetadataEntry>} headEntries
+ */
+export const buildStabilityOverview = headEntries =>


I just have an idea if an api have on top metadata description is should be add under the name/link as <p>

avivkeller · 2026-05-05T19:48:00Z

@nodejs/web-infra this should be our last major blocker, so PTAL

feat(web): add all.html generation

7d9abc6

Copilot AI review requested due to automatic review settings April 29, 2026 20:43

avivkeller requested a review from a team as a code owner April 29, 2026 20:43

avivkeller review requested due to automatic review settings April 29, 2026 20:44

Copilot started reviewing on behalf of avivkeller April 29, 2026 20:44 View session

vercel Bot deployed to Preview April 29, 2026 20:44 View deployment

avivkeller mentioned this pull request Apr 29, 2026

Generate index.html and 404.html programatically #620

Open

fixup!

5decb29

avivkeller changed the title ~~feat(web): add all.html generation~~ feat(web): add all, index, and 404 generation Apr 29, 2026

vercel Bot deployed to Preview April 29, 2026 21:34 View deployment

avivkeller marked this pull request as draft April 29, 2026 21:38

fixup!

cbf00f0

avivkeller marked this pull request as ready for review April 29, 2026 22:28

vercel Bot deployed to Preview April 29, 2026 22:30 View deployment

avivkeller requested a review from AugustinMauroy April 29, 2026 22:30

AugustinMauroy reviewed Apr 30, 2026

View reviewed changes

Comment thread src/generators/web/utils/synthetic/404.mjs

AugustinMauroy reviewed Apr 30, 2026

View reviewed changes

Comment thread src/generators/web/utils/synthetic/index.mjs Outdated

fixup!

468b6ce

vercel Bot deployed to Preview May 4, 2026 20:40 View deployment

avivkeller requested a review from AugustinMauroy May 4, 2026 20:40

cursor Bot reviewed May 4, 2026

View reviewed changes

AugustinMauroy approved these changes May 5, 2026

View reviewed changes

Conversation

avivkeller commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

orama-db Generator

web Generator

Uh oh!

Uh oh!

Uh oh!

AugustinMauroy commented Apr 30, 2026

Uh oh!

AugustinMauroy commented Apr 30, 2026

Uh oh!

avivkeller commented Apr 30, 2026

Uh oh!

AugustinMauroy commented May 1, 2026

Uh oh!

avivkeller commented May 2, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot May 4, 2026

Choose a reason for hiding this comment

Index entry unconditionally removed regardless of config

Uh oh!

AugustinMauroy left a comment

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy May 5, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

avivkeller commented Apr 29, 2026 •

edited

Loading

vercel Bot commented Apr 29, 2026 •

edited

Loading

cursor Bot commented Apr 29, 2026 •

edited

Loading

codecov Bot commented Apr 29, 2026 •

edited

Loading

github-actions Bot commented Apr 29, 2026 •

edited

Loading

`orama-db` Generator

`web` Generator