feat(`web`): introduce stability overview by AugustinMauroy · Pull Request #644 · nodejs/doc-kit

AugustinMauroy · 2026-03-05T09:15:45Z

Description

introduce stability overview on new web generator

Validation

It's should be cool 😎

Related Issues

Close #357

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 & node --run lint.
I've covered new added functionality with unit tests if necessary.

vercel · 2026-03-05T09:15:50Z

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Mar 5, 2026 9:44pm

codecov · 2026-03-05T09:16:33Z

Codecov Report

❌ Patch coverage is 75.40984% with 45 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.93%. Comparing base (acb4c34) to head (83203ee).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/generators/jsx-ast/generate.mjs	0.00%	24 Missing ⚠️
src/generators/jsx-ast/utils/buildContent.mjs	12.50%	21 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #644      +/-   ##
==========================================
+ Coverage   75.90%   75.93%   +0.02%     
==========================================
  Files         145      147       +2     
  Lines       13735    13910     +175     
  Branches      992     1001       +9     
==========================================
+ Hits        10426    10562     +136     
- Misses       3303     3342      +39     
  Partials        6        6

☔ 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-03-05T09:17:55Z

`web` Generator

File	Base	Head	Diff
`documentation.html`	36.92 KB	50.38 KB	+13.46 KB (+36.44%)
`documentation.js`	9.74 KB	21.57 KB	+11.83 KB (+121.41%)
`styles.css`	137.01 KB	141.80 KB	+4.79 KB (+3.50%)
`index.js`	9.69 KB	9.70 KB	+15.00 B (+0.15%)
`embedding.js`	37.29 KB	37.30 KB	+5.00 B (+0.01%)
`intl.js`	37.08 KB	37.08 KB	+5.00 B (+0.01%)
`synopsis.js`	15.72 KB	15.72 KB	+5.00 B (+0.03%)

Copilot

Pull request overview

Introduces a “Stability Overview” table to the new web generator output, mirroring the legacy generator’s ability to render a stability summary on the “About”/documentation page when slot tags are present.

Changes:

Add StabilityOverview UI component (CSS + JSX) and register it in web JSX import mapping.
Precompute and pass stability overview entries through the jsx-ast generator pipeline, injecting the table when the slot tag is present.
Ensure the web generator creates the output directory before writing HTML/JS/CSS artifacts.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/generators/web/ui/components/StabilityOverview/index.module.css	Adds minimal layout styling for the stability overview table and badge cell.
src/generators/web/ui/components/StabilityOverview/index.jsx	Implements the stability overview table UI using `Badge` tooltips.
src/generators/web/generate.mjs	Creates `config.output` directory before emitting generated files.
src/generators/web/constants.mjs	Registers `StabilityOverview` in `JSX_IMPORTS` for bundling/import generation.
src/generators/jsx-ast/utils/buildContent.mjs	Threads stability overview entries through `processEntry` and injects the component when slot tags are present.
src/generators/jsx-ast/generate.mjs	Precomputes stability overview data once and passes it to workers via the `extra` stream context.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/generators/jsx-ast/utils/buildContent.mjs

src/generators/web/ui/components/StabilityOverview/index.jsx

src/generators/web/generate.mjs

avivkeller

I wonder if adding stability to the sidebar would be better?

AugustinMauroy · 2026-03-07T22:29:44Z

I wonder if adding stability to the sidebar would be better?

It's should be on toc ? it's already

ovflowd · 2026-03-08T02:13:26Z

I wonder if adding stability to the sidebar would be better?

It's should be on toc ? it's already

I wonder if Aviv meant completely being there or maybe always being there? Although that seems a discussion for another issue.

ovflowd · 2026-03-08T02:13:48Z

src/generators/jsx-ast/utils/buildStabilityOverview.mjs

+
+const STABILITY_KINDS = ['error', 'warning', 'default', 'info'];
+
+/**


nit: remove this empty doc

if we remove it es-lint ask for it but it's doesn't require any jsdoc

Just remove it or do proper JSdoc for it.

ovflowd · 2026-03-08T02:14:53Z

src/generators/jsx-ast/generate.mjs

+    .filter(node => node.stability?.children?.length)
+    .map(({ api, heading, stability }) => {
+      const [{ data }] = stability.children;
+      return {


Could this map fn be moved to a dedicated function and be unit tested? Thanks!

seem reasonable

ovflowd · 2026-03-08T02:15:01Z

src/generators/jsx-ast/generate.mjs


+  // Pre-compute stability overview data once — avoid serialising full AST nodes to workers
+  const stabilityOverviewEntries = headNodes
+    .filter(node => node.stability?.children?.length)


Suggested change

.filter(node => node.stability?.children?.length)

.filter(node => !!node.stability?.children?.length)

oh 🤓 that's smart

ovflowd · 2026-03-08T02:23:51Z

src/generators/jsx-ast/utils/buildContent.mjs

  );

+  // Inject the stability overview table where the slot tag is present
+  if (


I wonder how optimal this is... I wonder if a visit statement is better here, I also kinda dislike this method of inserting the stability index.

ovflowd

This method would make sense for legacy docs. For the new docs, this method isn't really acceptable. The stability overview must be a React component now for the web generator, and all that we must do here is replace the STABILITY_OVERVIEW_SLOT_BEGIN or IDK with a slot for the component.

This would also make it easier to maintain the component.

AugustinMauroy · 2026-03-08T09:43:56Z

This method would make sense for legacy docs. For the new docs, this method isn't really acceptable. The stability overview must be a React component now for the web generator, and all that we must do here is replace the STABILITY_OVERVIEW_SLOT_BEGIN or IDK with a slot for the component.

This would also make it easier to maintain the component.

i do that but aviv ask for AST approach #644 (comment)

So what should I do ?

avivkeller · 2026-03-08T12:20:57Z

I asked for an AST approach for generating a table, however, if that's not possible for a sidebar, we don't have to do it.

I meant, the badge that you have in the table might be better suited in the sidebar, WDYT?

ovflowd · 2026-03-08T12:56:55Z

I asked for an AST approach for generating a table, however, if that's not possible for a sidebar, we don't have to do it.

I meant, the badge that you have in the table might be better suited in the sidebar, WDYT?

I understand why an AST approach, but I'd prefer a React component here, we're using AST trees for building the structure of the page, which is fine I guess? But I'd rather have it being a React tree, not gonna lie. For example a lot of things are done in places that don't make much sense for me, for example https://github.com/nodejs/doc-kit/blob/main/src/generators/jsx-ast/utils/buildContent.mjs#L289-L316, we're building the document tree in JSX here by using this ast.mjs file (https://github.com/nodejs/doc-kit/blob/main/src/generators/jsx-ast/utils/ast.mjs) and this is awkward as hell for me and hard to maintain. If we ever want to make change to the document tree or customizing props, this is going to be incredibly hard for newcomers.

I was never fan of this approach but initially it was simple, now it is overly complex. We're hand-crafting JSX elements here, where the reality is we could just make regular React Components (JSX Components/Elements)..

The other part that hinders customization of doc-kit is that we already wire straight on the jsx-ast generator our own ui-components which limit in the future if people want to have other layouts/designs or use their own components for the structure of their docs.

This is more of a long-term ask, but I do feel we should try to make the customization and maintainability here as easy as possible, but the jsx-ast seems to be doing too much stuff and too much hard-coded (https://github.com/nodejs/doc-kit/tree/main/src/generators/jsx-ast)...

It'd be great if the Stability Overview is its own component. Could be on node-core/ui-components or specifically in the components folder on the web generator.

avivkeller · 2026-03-08T13:33:49Z

Building the AST directly results in both faster, smaller, and more memory efficient builds.

It's a little off putting for new comers, I suppose, however, thats nothing some documentation can't fix.

I disagree that everything should be a client-side JSX element, I think that JSX elements should only be used when an AST implementation is not feasible.

avivkeller · 2026-03-08T13:35:34Z

The other part that hinders customization of doc-kit is that we already wire straight on the jsx-ast generator our own ui-components which limit in the future if people want to have other layouts/designs or use their own components for the structure of their docs.

That's something that can definitely be changed. For instance, we allow customization of the logo, we can allow customization of everything else.

avivkeller · 2026-03-08T13:37:38Z

@ovflowd if you have an issue with the current approach, feel free to open a designated issue and voice your concerns, which others can agree or refute

ovflowd · 2026-03-08T18:03:13Z

I disagree that everything should be a JSX element, I think that JSX elements should only be used when an AST implementation is not feasible.

You are literally creating JSX elements manually on jsx-ast...

ovflowd · 2026-03-08T18:03:37Z

It's a little off putting for new comers, I suppose, however, thats nothing some documentation can't fix.

How you see customization of the tree or document or components with the current hard-coded jsx tree?

ovflowd · 2026-03-08T20:37:06Z

Btw, I still believe this should be a React component. I'm 👎 with the current approach because I know we can make it simpler with React, but if that's too much trouble, I can waive my block.

AugustinMauroy · 2026-03-08T20:50:45Z

@avivkeller agree that I should comme back to react component ?

feat(web): introduce stability overview

113fbbe

Copilot AI review requested due to automatic review settings March 5, 2026 09:15

AugustinMauroy requested a review from a team as a code owner March 5, 2026 09:15

Copilot started reviewing on behalf of AugustinMauroy March 5, 2026 09:16 View session

AugustinMauroy marked this pull request as draft March 5, 2026 09:22

Copilot AI reviewed Mar 5, 2026

View reviewed changes

src/generators/jsx-ast/utils/buildContent.mjs Outdated Show resolved Hide resolved

src/generators/jsx-ast/utils/buildContent.mjs Show resolved Hide resolved

src/generators/web/ui/components/StabilityOverview/index.jsx Outdated Show resolved Hide resolved

avivkeller reviewed Mar 5, 2026

View reviewed changes

src/generators/web/ui/components/StabilityOverview/index.jsx Outdated Show resolved Hide resolved

src/generators/web/generate.mjs Outdated Show resolved Hide resolved

Update generate.mjs

df3c7a5

vercel bot deployed to Preview March 5, 2026 20:55 View deployment

update

95229d1

vercel bot deployed to Preview March 5, 2026 21:33 View deployment

Create buildStabilityOverview.test.mjs

f2b9366

vercel bot deployed to Preview March 5, 2026 21:43 View deployment

Merge branch 'main' into augu-stability-overview-web

83203ee

AugustinMauroy marked this pull request as ready for review March 5, 2026 21:44

vercel bot deployed to Preview March 5, 2026 21:44 View deployment

avivkeller reviewed Mar 7, 2026

View reviewed changes

ovflowd reviewed Mar 8, 2026

View reviewed changes

ovflowd requested changes Mar 8, 2026

View reviewed changes

ovflowd mentioned this pull request Mar 8, 2026

discussion: doc-kit jsx-ast generator manual paths and customization #661

Open


		const STABILITY_KINDS = ['error', 'warning', 'default', 'info'];

		/**

	.filter(node => node.stability?.children?.length)
	.filter(node => !!node.stability?.children?.length)

Conversation

AugustinMauroy commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Validation

Related Issues

Check List

Uh oh!

vercel bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Mar 5, 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 Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

web Generator

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

avivkeller left a comment

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy commented Mar 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ovflowd commented Mar 8, 2026

Uh oh!

ovflowd Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ovflowd left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy commented Mar 8, 2026

Uh oh!

avivkeller commented Mar 8, 2026

Uh oh!

ovflowd commented Mar 8, 2026

Uh oh!

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

Uh oh!

Uh oh!

avivkeller commented Mar 8, 2026

Uh oh!

avivkeller commented Mar 8, 2026

Uh oh!

ovflowd commented Mar 8, 2026

AugustinMauroy commented Mar 5, 2026 •

edited

Loading

vercel bot commented Mar 5, 2026 •

edited

Loading

codecov bot commented Mar 5, 2026 •

edited

Loading

github-actions bot commented Mar 5, 2026 •

edited

Loading

`web` Generator

AugustinMauroy commented Mar 7, 2026 •

edited

Loading

ovflowd Mar 8, 2026 •

edited

Loading

ovflowd left a comment •

edited

Loading

avivkeller commented Mar 8, 2026 •

edited

Loading