chore: make doc-kit friendly

[avivkeller]

Ahead of RenderATL, this PR makes doc-kit user friendly with:

• doc-kit serve
• doc-kit bootstrap
• doc-kit install

• updated the docs to include information about packages, these commands, and getting started.

cc @ovflowd @bmuenzenmeyer I'll open a PR when this lands to remove the Node.js-isms, figured this one was. big enough

[cursor]

PR Summary

Medium Risk
New CLI paths spawn package managers and run a local HTTP server with file watching; impact is mostly local dev UX, with solid test coverage on the server layer but broader surface area for regressions in onboarding and preview workflows.

Overview
Adds three user-facing CLI commands so projects can onboard and preview docs without manual wiring: bootstrap creates doc-kit.config.mjs (linked to package.json), a docs directory with a starter page, .gitignore for output, and optional generator package installs; install resolves built-in targets to companion packages and runs the detected package manager; serve runs generation, serves the output over HTTP (with extension-less URL handling), watches inputs, and debounces rebuilds, with --static to preview existing output only.

generate and serve now share configuration flags via createConfigurationOptions. A new packages/core/src/server module implements static serving, safe path resolution, port fallback, and the rebuild scheduler (covered by tests).

Documentation is reorganized for general adopters: new guides (writing docs, customization, publishing, troubleshooting, CLI reference), creating-generators split out from the generators overview, and getting-started flows center on bootstrap + serve. CLI/help text is de-emphasized as Node-only (e.g. “target project version”, built-in target html instead of web). E2E preview uses doc-kit serve --static instead of npx serve.

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Aug 4, 2026 4:12pm

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov]

Codecov Report

❌ Patch coverage is 65.06986% with 525 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.10%. Comparing base (c334823) to head (a13933b).

Files with missing lines	Patch %	Lines
packages/core/bin/commands/bootstrap.mjs	0.00%	186 Missing ⚠️
packages/core/bin/commands/serve.mjs	0.00%	96 Missing ⚠️
www/doc-kit.config.mjs	0.00%	66 Missing ⚠️
packages/core/bin/commands/install.mjs	0.00%	55 Missing ⚠️
packages/core/bin/commands/options.mjs	0.00%	39 Missing ⚠️
packages/core/src/utils/install.mjs	82.88%	32 Missing ⚠️
packages/core/src/server/index.mjs	88.78%	24 Missing and 1 partial ⚠️
packages/core/bin/commands/generate.mjs	0.00%	11 Missing ⚠️
scripts/build-docs-content.mjs	0.00%	9 Missing ⚠️
packages/core/bin/commands/index.mjs	0.00%	4 Missing ⚠️
... and 2 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #999      +/-   ##
==========================================
- Coverage   89.63%   88.10%   -1.54%     
==========================================
  Files         200      210      +10     
  Lines       18501    19934    +1433     
  Branches     1729     1860     +131     
==========================================
+ Hits        16584    17562     +978     
- Misses       1910     2364     +454     
- Partials        7        8       +1     

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

api-links Generator

Output: 1 file differs

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#L293',
    'Buffer.alloc': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L435',
    'Buffer.allocUnsafe': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L449',
    'Buffer.allocUnsafeSlow': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L461',
...
    'agent.addRequest': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L358',
+   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L332',
-   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L297',
    'agent.createSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L429',
    'agent.destroy': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L662',
+   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L515',
+   'agent.keepSocketAlive': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L484',
-   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L327',
-   'agent.keepSocketAlive': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L618',
    'agent.removeSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L557',
    'agent.reuseSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L654',
    '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#L243',
    'asyncResource.bind': 'https://github.com/nodejs/node/blob/HEAD/lib/async_hooks.js#L275',
...
    'server.address': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2699',
+   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2832',
+   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L124',
+   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L126',
-   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L681',
-   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L691',
-   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L703',
    'server.getConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2794',
    'server.listen': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2496',
    'server.ref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2945',
+   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L128',
-   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L719',
    'server.unref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2954',
+   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2872',
-   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L687',
    'server[SymbolAsyncIterator]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2879',
    'server[kDeserialize]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2419',
    'server[kTransferList]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2392',
    'server[kTransfer]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2397',
+   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2909',
-   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L726',
    'serverresponse._finish': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L254',
    'serverresponse._implicitHeader': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L411',
    'serverresponse.assignSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L304',
    'serverresponse.detachSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L315',
    'serverresponse.statusCode': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L277',

Performance estimate _{(single CI run)}

• Generation time: 6.2% slower (1.46 s → 1.55 s)
• Peak memory: 2.2% lower (356.27 MB → 348.55 MB)

legacy-html Generator

Performance estimate _{(single CI run)}

• Generation time: 3.8% faster (19.72 s → 18.98 s)
• Peak memory: 2.3% lower (2.15 GB → 2.10 GB)

legacy-json Generator

Performance estimate _{(single CI run)}

• Generation time: 7.9% slower (7.84 s → 8.46 s)
• Peak memory: 10.4% higher (1.57 GB → 1.73 GB)

llms-txt Generator

Performance estimate _{(single CI run)}

• Generation time: 6.2% faster (8.98 s → 8.42 s)
• Peak memory: 15.3% lower (1.85 GB → 1.57 GB)

orama-db Generator

Output size: 1 file changed · net +1.00 B

File size details

File	Main	PR	Change
orama-db.json	9.03 MB	9.03 MB	+1.00 B (+0.0%)

Performance estimate _{(single CI run)}

• Generation time: 5.1% slower (8.08 s → 8.49 s)
• Peak memory: 12.2% lower (1.91 GB → 1.68 GB)

web Generator

Output size: 1 file changed · net -112.00 B

File size details

File	Main	PR	Change
all.html	31.41 MB	31.41 MB	-112.00 B (-0.0%)

Performance estimate _{(single CI run)}

• Generation time: 1.3% slower (83.89 s → 84.98 s)
• Peak memory: 6.1% higher (4.65 GB → 4.93 GB)

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

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

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

[ovflowd]

What exactly an install command does for us?

[ovflowd]

I don't think we should have an install command. We should defer to package managers to install packages. Not doc-kit, I don't think any other tool does something like that.

[avivkeller]

We spoke in the meeting about the concern of users not being able to remember the names of packages (e.g. @nodejs/doc-kit-generator-react), so I figured a shorthand to install them would make sense

[ovflowd]

Are we making some sort of CRA but for doc-kit?

[avivkeller]

Yes and no. Yes, it's a CRA, but it adapts to already set up documentation, rather than creating a whole new app with a package.json, etc

[ovflowd]

Actually, I feel this requires more thought/reviews before proceeding with this. I'm unsure how I feel with this. Could you create an issue so we can chat about the api design regarding a "create react app" sort of wrapper for doc-kit?

[avivkeller]

@ovflowd done, but what are your concerns?

[ovflowd]

@ovflowd done, but what are your concerns?

If doing this is the right path. Even React abandoned housing something like CRA. I get that some tools, such as Next.js themselves have also a way to bootstrap a Next.js app, but I'd argue this shouldn't be part of doc-kit itself, nor we should rewrite our commands to acommodate that. It should probably be its own package, within the monorepo (maybe?)

Plus the PR is introducing 3 different commands:

• serve feels like unnecessary, we don't need to have serve by ourselves imo, doc-kit is not a server, shouldn't try to be at this stage. Defer to users how they want to serve, can be as easy as npx serve
• bootstrap is complex needs proper discussion on how it works
• install feels like it's not something doc-kit should do, only package managers. I'd argue that the bootstrap command could allow you to select with generators to install. But in general we shouldn't have a helper for that. Think of unified, they have hundreds of packages. It's often easy to find what you need by looking at docs. AIs can also help.

[avivkeller]

serve feels like unnecessary, we don't need to have serve by ourselves imo, doc-kit is not a server, shouldn't try to be at this stage. Defer to users how they want to serve, can be as easy as npx serve

Serve does not than just serve, it also watches for changes and reports on errors, so users can build + watch their docs, such as docusaurus start.

[avivkeller]

install feels like it's not something doc-kit should do, only package managers. I'd argue that the bootstrap command could allow you to select with generators to install. But in general we shouldn't have a helper for that. Think of unified, they have hundreds of packages. It's often easy to find what you need by looking at docs. AIs can also help.

I'm thinking about users who know the name of the generator they want, but not which package it is in. It's fairly simple for us to resolve that by adding a basic downloading command. Bootstrap does this, fwiw.

[ovflowd]

serve feels like unnecessary, we don't need to have serve by ourselves imo, doc-kit is not a server, shouldn't try to be at this stage. Defer to users how they want to serve, can be as easy as npx serve

Serve does not than just serve, it also watches for changes and reports on errors, so users can build + watch their docs, such as docusaurus start.

Again, unsure if this is needed/should be owned by us. Would appreciate consensus first 🙈

[ovflowd]

install feels like it's not something doc-kit should do, only package managers. I'd argue that the bootstrap command could allow you to select with generators to install. But in general we shouldn't have a helper for that. Think of unified, they have hundreds of packages. It's often easy to find what you need by looking at docs. AIs can also help.

I'm thinking about users who know the name of the generator they want, but not which package it is in. It's fairly simple for us to resolve that by adding a basic downloading command. Bootstrap does this, fwiw.

That's fair, but can't they just go to the website, open searchbar and do that? Why a whole command for that?

[bmuenzenmeyer]

the entirety of a getting started experience currently fits "above the fold" within https://doc-kit.nodejs.org/getting-started.html - you can go from empty project to something rendered in seconds.

i agree that serve/watch might be the most useful. installation i usually prefer to be ergonomic to package managers. users wants to install things in this security environment

my two cents. i probably didnt think through it as deeply as i should have when you asked in Slack Aviv.

this body of work is less important to me than making the defaults generic.

sample size is small. getting more feedback is a good idea

[avivkeller]

If I broke out the commands into idiomatic PRs, and the docs into this PR, would that be able to land the better docs before render?