feat: add mdx support by avivkeller · Pull Request #845 · nodejs/doc-kit

avivkeller · 2026-06-19T18:46:02Z

This PR adds the ability for input files to support MDX syntax (e.g. JSX components and such)

vercel · 2026-06-19T18:46:08Z

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jun 19, 2026 8:12pm

cursor · 2026-06-19T18:46:10Z

PR Summary

Medium Risk
Touches the core parse → metadata → render pipeline; incorrect MDX detection could mis-handle Node core .md type syntax or skip needed API transforms on mixed content.

Overview
Adds JSX-in-MDX for doc-kit content while keeping existing .md API docs on the markdown path where <type> and {type} stay literal annotations.

The AST stage picks markdown vs MDX via .mdx, optional frontmatter mdx: true/false, and remark-mdx through new getRemarkMdx(). MDX strips frontmatter before parse (HTML comments are invalid MDX) and re-attaches it as the YAML html node metadata expects. Each parsed file now carries an mdx flag through metadata.

When mdx is true, metadata and JSX-AST stages skip API-doc transforms: no {type} link rewriting and no strongly-typed list → signature tables, so real JSX/expression nodes are preserved. The remark/rehype/recma pipeline already passes MDX node types through.

The web generator gains web.components (tag → import, with shorthand) merged into client/server bundle imports alongside built-ins, documented in the web README. Version bumps to 1.4.0 with remark-mdx dependency.

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

codecov · 2026-06-19T18:47:02Z

Codecov Report

❌ Patch coverage is 98.84058% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.75%. Comparing base (5cf8968) to head (df43a77).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/generators/ast/generate.mjs	97.05%	2 Missing ⚠️
src/generators/web/utils/generate.mjs	90.47%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #845      +/-   ##
==========================================
+ Coverage   84.56%   84.75%   +0.19%     
==========================================
  Files         176      177       +1     
  Lines       15811    16127     +316     
  Branches     1412     1459      +47     
==========================================
+ Hits        13371    13669     +298     
- Misses       2430     2448      +18     
  Partials       10       10

☔ 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.

github-actions · 2026-06-19T18:48:51Z

`api-links` Generator

apilinks.json

Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    'Agent.defaultMaxSockets': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L239',
    'Buffer.alloc': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L433',
    'Buffer.allocUnsafe': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L447',
    'Buffer.allocUnsafeSlow': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L459',
...
    'agent.addRequest': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L304',
+   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L243',
-   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L326',
    'agent.createSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L375',
    'agent.destroy': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L608',
+   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L273',
-   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L484',
    'agent.keepSocketAlive': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L564',
    'agent.removeSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L503',
    'agent.reuseSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L600',
    'assert.assert': 'https://github.com/nodejs/node/blob/HEAD/lib/assert.js#L185',
    'asyncResource.asyncId': 'https://github.com/nodejs/node/blob/HEAD/lib/async_hooks.js#L242',
...
    'server.address': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2310',
+   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L671',
+   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L681',
+   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L693',
-   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2443',
-   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L120',
-   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L122',
    'server.getConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2405',
    'server.listen': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2127',
    'server.ref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2548',
+   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L709',
-   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L124',
    'server.unref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2557',
+   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L677',
+   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L716',
-   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2483',
-   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2512',
    'serverresponse._finish': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L246',
    'serverresponse._implicitHeader': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L403',
    'serverresponse.assignSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L296',
    'serverresponse.detachSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L307',
    'serverresponse.statusCode': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L269',
...
    'socket.addSourceSpecificMembership': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L1043',
+   'socket.address': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L932',
-   'socket.address': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L733',
    'socket.bind': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L284',
    'socket.bindSync': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L437',
    'socket.close': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L895',
+   'socket.connect': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L481',
-   'socket.connect': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L1300',
    'socket.connectSync': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L514',
    'socket.destroySoon': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L875',
    'socket.disconnect': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L607',
    'socket.dropMembership': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L1028',
    'socket.dropSourceSpecificMembership': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L1061',
...
    'socket.read': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L858',
+   'socket.ref': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L1118',
-   'socket.ref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L1640',
    'socket.remoteAddress': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L944',
    'socket.resetAndDestroy': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L820',
    'socket.resume': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L849',
    'socket.send': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L732',
    'socket.sendto': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L621',
...
    'socket.setTypeOfService': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L680',
+   'socket.unref': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L1128',
-   'socket.unref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L1654',
    'socket[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/dgram.js#L919',
    'socket[kAfterAsyncWrite]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L1009',
    'socket[kReinitializeHandle]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L1368',
    'string_decoder.StringDecoder': 'https://github.com/nodejs/node/blob/HEAD/lib/string_decoder.js#L60',
    'timers.clearImmediate': 'https://github.com/nodejs/node/blob/HEAD/lib/timers.js#L226',

`web` Generator

File	Base	Head	Diff
`addons.js`	305.26 KB	305.26 KB	+7.00 B (+0.00%)
`assert.js`	448.95 KB	448.95 KB	+7.00 B (+0.00%)
`async_context.js`	213.43 KB	213.43 KB	+7.00 B (+0.00%)
`async_hooks.js`	191.51 KB	191.52 KB	+7.00 B (+0.00%)
`buffer.js`	1.08 MB	1.08 MB	+7.00 B (+0.00%)
`child_process.js`	455.00 KB	455.01 KB	+7.00 B (+0.00%)
`cli.js`	314.94 KB	314.95 KB	+7.00 B (+0.00%)
`cluster.js`	188.56 KB	188.57 KB	+7.00 B (+0.00%)
`console.js`	99.13 KB	99.14 KB	+7.00 B (+0.01%)
`crypto.js`	1.22 MB	1.22 MB	+7.00 B (+0.00%)
`debugger.js`	88.91 KB	88.91 KB	+7.00 B (+0.01%)
`deprecations.js`	294.46 KB	294.47 KB	+7.00 B (+0.00%)
`dgram.js`	179.27 KB	179.28 KB	+7.00 B (+0.00%)
`diagnostics_channel.js`	303.25 KB	303.26 KB	+7.00 B (+0.00%)
`dns.js`	261.77 KB	261.77 KB	+7.00 B (+0.00%)
`documentation.js`	4.84 KB	4.85 KB	+7.00 B (+0.14%)
`domain.js`	85.64 KB	85.65 KB	+7.00 B (+0.01%)
`dtls.js`	82.81 KB	82.82 KB	+7.00 B (+0.01%)
`embedding.js`	33.39 KB	33.40 KB	+7.00 B (+0.02%)
`environment_variables.js`	11.70 KB	11.70 KB	+7.00 B (+0.06%)
`errors.js`	360.67 KB	360.68 KB	+7.00 B (+0.00%)
`esm.js`	131.90 KB	131.91 KB	+7.00 B (+0.01%)
`events.js`	539.11 KB	539.12 KB	+7.00 B (+0.00%)
`ffi.js`	97.13 KB	97.14 KB	+7.00 B (+0.01%)
`fs.js`	1.27 MB	1.27 MB	+7.00 B (+0.00%)
`globals.js`	122.78 KB	122.79 KB	+7.00 B (+0.01%)
`http.js`	687.21 KB	687.22 KB	+7.00 B (+0.00%)
`http2.js`	803.01 KB	803.02 KB	+7.00 B (+0.00%)
`https.js`	155.22 KB	155.23 KB	+7.00 B (+0.00%)
`inspector.js`	114.90 KB	114.91 KB	+7.00 B (+0.01%)
`intl.js`	32.41 KB	32.42 KB	+7.00 B (+0.02%)
`module.js`	331.70 KB	331.70 KB	+7.00 B (+0.00%)
`modules.js`	146.23 KB	146.24 KB	+7.00 B (+0.00%)
`n-api.js`	711.13 KB	711.14 KB	+7.00 B (+0.00%)
`net.js`	279.40 KB	279.41 KB	+7.00 B (+0.00%)
`os.js`	103.20 KB	103.21 KB	+7.00 B (+0.01%)
`packages.js`	145.83 KB	145.84 KB	+7.00 B (+0.00%)
`path.js`	91.92 KB	91.92 KB	+7.00 B (+0.01%)
`perf_hooks.js`	353.59 KB	353.59 KB	+7.00 B (+0.00%)
`permissions.js`	34.79 KB	34.79 KB	+7.00 B (+0.02%)
`process.js`	695.92 KB	695.92 KB	+7.00 B (+0.00%)
`punycode.js`	23.41 KB	23.42 KB	+7.00 B (+0.03%)
`querystring.js`	26.14 KB	26.14 KB	+7.00 B (+0.03%)
`quic.js`	442.69 KB	442.70 KB	+7.00 B (+0.00%)
`readline.js`	217.31 KB	217.32 KB	+7.00 B (+0.00%)
`repl.js`	205.07 KB	205.08 KB	+7.00 B (+0.00%)
`report.js`	184.70 KB	184.71 KB	+7.00 B (+0.00%)
`single-executable-applications.js`	80.17 KB	80.18 KB	+7.00 B (+0.01%)
`sqlite.js`	254.82 KB	254.82 KB	+7.00 B (+0.00%)
`stream.js`	853.68 KB	853.69 KB	+7.00 B (+0.00%)
`stream_iter.js`	452.79 KB	452.80 KB	+7.00 B (+0.00%)
`string_decoder.js`	26.63 KB	26.63 KB	+7.00 B (+0.03%)
`synopsis.js`	11.39 KB	11.40 KB	+7.00 B (+0.06%)
`test.js`	921.62 KB	921.63 KB	+7.00 B (+0.00%)
`timers.js`	93.30 KB	93.30 KB	+7.00 B (+0.01%)
`tls.js`	308.23 KB	308.24 KB	+7.00 B (+0.00%)
`tracing.js`	72.75 KB	72.75 KB	+7.00 B (+0.01%)
`tty.js`	43.05 KB	43.05 KB	+7.00 B (+0.02%)
`typescript.js`	21.57 KB	21.57 KB	+7.00 B (+0.03%)
`url.js`	330.81 KB	330.81 KB	+7.00 B (+0.00%)
`util.js`	745.90 KB	745.90 KB	+7.00 B (+0.00%)
`v8.js`	345.20 KB	345.21 KB	+7.00 B (+0.00%)
`vfs.js`	43.09 KB	43.09 KB	+7.00 B (+0.02%)
`vm.js`	432.13 KB	432.14 KB	+7.00 B (+0.00%)
`wasi.js`	37.79 KB	37.79 KB	+7.00 B (+0.02%)
`webcrypto.js`	422.15 KB	422.16 KB	+7.00 B (+0.00%)
`webstreams.js`	280.03 KB	280.03 KB	+7.00 B (+0.00%)
`worker_threads.js`	394.12 KB	394.13 KB	+7.00 B (+0.00%)
`zlib.js`	359.52 KB	359.53 KB	+7.00 B (+0.00%)

AugustinMauroy

maybe add test ?

cursor

Cursor Bugbot has reviewed your changes using default effort 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 df43a77. Configure here.}

feat: add mdx support

c23d65f

avivkeller requested a review from a team as a code owner June 19, 2026 18:46

vercel Bot deployed to Preview June 19, 2026 18:46 View deployment

cursor Bot reviewed Jun 19, 2026

View reviewed changes

Comment thread src/generators/web/utils/generate.mjs

avivkeller mentioned this pull request Jun 19, 2026

feat: add home page webpack/webpack-doc-kit#149

Open

AugustinMauroy reviewed Jun 19, 2026

View reviewed changes

feat: add mdx support

df43a77

vercel Bot deployed to Preview June 19, 2026 20:12 View deployment

cursor Bot reviewed Jun 19, 2026

View reviewed changes

Comment thread src/generators/metadata/utils/parse.mjs

AugustinMauroy approved these changes Jun 20, 2026

View reviewed changes

bjohansebas approved these changes Jun 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add mdx support#845

feat: add mdx support#845
avivkeller wants to merge 2 commits into
mainfrom
add-mdx-support

avivkeller commented Jun 19, 2026

Uh oh!

vercel Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

cursor Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

AugustinMauroy left a comment

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

avivkeller commented Jun 19, 2026

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

PR Summary

Uh oh!

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

Uh oh!

api-links Generator

web Generator

Uh oh!

Uh oh!

AugustinMauroy left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented Jun 19, 2026 •

edited

Loading

cursor Bot commented Jun 19, 2026 •

edited

Loading

codecov Bot commented Jun 19, 2026 •

edited

Loading

github-actions Bot commented Jun 19, 2026 •

edited

Loading

`api-links` Generator

`web` Generator