feat(docs): add documentation for `doc-kit` by bmuenzenmeyer · Pull Request #889 · nodejs/doc-kit

bmuenzenmeyer · 2026-07-10T21:15:19Z

Description

Introduces the doc-kit documentation site, built with doc-kit!
This also serves as a reasonable simple web example.

Validation

npm run docs:build
npx serve www/out

Getting started suggestion end-state

Related Issues

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.

… the spec

vercel · 2026-07-10T21:15:24Z

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jul 12, 2026 3:51am

codecov · 2026-07-10T21:16:09Z

Codecov Report

❌ Patch coverage is 0% with 260 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.87%. Comparing base (d7bdf39) to head (3f035e7).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
www/theme/SideBar.jsx	0.00%	103 Missing ⚠️
scripts/build-docs-content.mjs	0.00%	82 Missing ⚠️
www/doc-kit.config.mjs	0.00%	75 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #889      +/-   ##
==========================================
- Coverage   85.04%   83.87%   -1.18%     
==========================================
  Files         179      183       +4     
  Lines       16496    16826     +330     
  Branches     1500     1513      +13     
==========================================
+ Hits        14029    14112      +83     
- Misses       2457     2704     +247     
  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-07-10T21:17:40Z

`web` Generator

File	Base	Head	Diff
`all.html`	19.94 MB	19.94 MB	-234.00 B (-0.00%)

AugustinMauroy

Noice !

also we should add a "why doc-kit" section but with a "TBD" and in future have comparison with fuma-docs/docausorus ...

AugustinMauroy · 2026-07-11T10:33:03Z

+      - name: Upload site artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: docs-site
+          path: www/out


what if we deploy the docs on GH page ?

i dont have strong opinions here other that continuing our current patterns.

cursor · 2026-07-12T02:20:16Z

PR Summary

Low Risk
Docs-only build pipeline, config, and markdown heading tweaks; no changes to core generator runtime behavior beyond what the site build invokes.

Overview
Adds a documentation site built with doc-kit’s own web and orama-db targets, plus CI that verifies the build on every PR and push to main.

A new docs:build flow runs scripts/build-docs-content.mjs to merge www/pages/*.md, root docs/*.md, and each generator’s README.md into gitignored www/content/, then generates static output under www/out/ via www/doc-kit.config.mjs (flat URLs, no synthetic Node.js index page, custom meta, repo-level edit link). GitHub Actions (docs.yml) runs npm ci and node --run docs:build, uploading www/out as an artifact.

Authoring includes new home and getting-started pages and a custom SideBar that splits “Pages” vs “Generators”, fixes guide order, and renders backtick headings as inline code. Generator READMEs are retitled from ## to # so they read correctly when pulled into the site. Minor tooling tweaks: ignore/format www/content, Prettier proseWrap for www/pages, and a target example in docs/configuration.md.

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

avivkeller · 2026-07-12T02:22:47Z

+ *
+ * @returns {Promise<Array<{ name: string, markdown: string }>>}
+ */
+const collectPages = async () => {


Would it be better to use a glob for this?

**/*.md?

i dont have strong opinions either way, but knew that i

wanted to clean out

load very specific subset of three possible patterns, but perhaps not other future markdown.

avivkeller · 2026-07-12T02:24:04Z

+The `legacy-html-all` target has no additional dependencies and is the quickest
+way to see output:


What does "no additional dependencies" mean? It depends on other generators (e.g. AST)

to run in the browser. it's html

avivkeller · 2026-07-12T02:29:20Z

+    // Pages are assembled into `www/content/` at build time, so there is no
+    // single source file a `{path}` template could point at. Link to the repo
+    // instead; a per-page link would need a `#theme/Metabar` override that maps
+    // each slug back to its true origin.
+    editURL: `https://github.com/${REPOSITORY}`,


We can also leave this blank to remove the link entirely

Co-authored-by: Aviv Keller <me@aviv.sh>

cursor

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

There are 4 total unresolved issues (including 3 from previous reviews).

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

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

AugustinMauroy · 2026-07-12T09:28:31Z

missing link to orama docs

a good follow up

bmuenzenmeyer added 4 commits July 10, 2026 16:08

setup CICD

c5118db

adds doc kit docs

139fcb4

reminds people that target can be supplied by config, not just flags

cdb9458

promote every heading up a level to make doc-kit rendering easier per…

1d783e3

… the spec

fix lint

09e884c

vercel Bot deployed to Preview July 11, 2026 00:23 View deployment

This was referenced Jul 11, 2026

fix(remark): preserve code display names through raw HTML #879

Merged

web generator should not render the search bar if orama-db is not enabled #891

Open

Support mermaid diagrams #892

Open

bmuenzenmeyer added 2 commits July 10, 2026 22:03

improve home page content, making sure to format pages

ec0d712

slight tweaks to getting started

65c26db

AugustinMauroy reviewed Jul 11, 2026

View reviewed changes

bmuenzenmeyer added 2 commits July 11, 2026 11:51

use node directly rather than npm

9426ef2

improve documentation based on feedback

82e80ef

vercel Bot deployed to Preview July 12, 2026 02:12 View deployment

add showcase

0f9fb0f

bmuenzenmeyer marked this pull request as ready for review July 12, 2026 02:20

bmuenzenmeyer requested a review from a team as a code owner July 12, 2026 02:20

vercel Bot deployed to Preview July 12, 2026 02:20 View deployment

cursor Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread scripts/vercel-docs-build.sh Outdated

Comment thread www/doc-kit.config.mjs

avivkeller changed the title ~~Doc kit docs~~ feat(docs): add documentation for doc-kit Jul 12, 2026

avivkeller reviewed Jul 12, 2026

View reviewed changes

bmuenzenmeyer and others added 4 commits July 11, 2026 22:21

Update www/pages/index.md

a49ea50

Co-authored-by: Aviv Keller <me@aviv.sh>

Update scripts/vercel-docs-build.sh

c7d5a19

Co-authored-by: Aviv Keller <me@aviv.sh>

Update www/pages/getting-started.md

9e7655c

Co-authored-by: Aviv Keller <me@aviv.sh>

Update www/pages/index.md

1f554c1

Co-authored-by: Aviv Keller <me@aviv.sh>

Update www/pages/getting-started.md

b714583

Co-authored-by: Aviv Keller <me@aviv.sh>

cursor Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread scripts/build-docs-content.mjs

vercel Bot deployed to Preview July 12, 2026 03:24 View deployment

Update www/pages/index.md

642a641

Co-authored-by: Aviv Keller <me@aviv.sh>

vercel Bot deployed to Preview July 12, 2026 03:26 View deployment

format after reviews

c0cb3d9

vercel Bot deployed to Preview July 12, 2026 03:49 View deployment

better consistency

3f035e7

vercel Bot deployed to Preview July 12, 2026 03:51 View deployment

cursor Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread scripts/build-docs-content.mjs

AugustinMauroy reviewed Jul 12, 2026

View reviewed changes

		The `legacy-html-all` target has no additional dependencies and is the quickest
		way to see output:

Uh oh!

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

web Generator

Uh oh!

AugustinMauroy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

PR Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bmuenzenmeyer commented Jul 10, 2026 •

edited

Loading

vercel Bot commented Jul 10, 2026 •

edited

Loading

codecov Bot commented Jul 10, 2026 •

edited

Loading

github-actions Bot commented Jul 10, 2026 •

edited

Loading

`web` Generator

cursor Bot commented Jul 12, 2026 •

edited

Loading