feat: redesign doc-kit.nodejs.org by ovflowd · Pull Request #1192 · nodejs/doc-kit

ovflowd · 2026-10-27T14:56:25Z

Description

This PR redesigns doc-kit.nodejs.org: a new theme and home page, illustrations for the guides, and a rewrite of the documentation itself. The whole site is built through doc-kit's own extension points (theme slots, components, stylesheets, a custom template and a rehype plugin), so it doubles as an example of how far you can take customizing doc-kit.

Site

A home page that shows what doc-kit does: an isometric hero, the sources and outputs of one kittens module, the worker pool building a site, benchmarks and a getting-started path. It's written in MDX (www/pages/index.mdx), and its code samples are plain fenced blocks, so they get doc-kit's own highlighting, code boxes, tabs and copy buttons. Only the two canvases, the sections' layout and a few hand-drawn previews are components.
A neutral theme over @node-core/ui-components, with light and dark modes, a cat logo, Inter, and styled search and theme menus.
Five isometric illustrations in the guides, inlined as SVG so they follow the color scheme. Each one lives on the page it explains.
www is its own private workspace package now (@doc-kit/www), so the site's dependencies stay out of the root package.json. It also holds the source of the social preview image (node --run og renders www/og/og.html) and the benchmark the home page quotes (node --run benchmark, which writes www/theme/benchmarks.json). The current numbers: this site's 40 pages build in 2.94 s, and the Node.js v26.12.1 API docs in 10.77 s.

Documentation

Every page, package README and generator README was rewritten and checked against the code. Guides teach a task with one running example; reference pages list every option, and the guides link to them instead of repeating them.
index.md became introduction.md, and there's a new guide for documenting TypeScript and JSDoc with @doc-kit/typedoc.
Every generator has its own page, in the same layout, including json-all, json-simple, llms-txt-full and the four legacy ones. The overview links all of them, and the sidebar keeps to the main ones. The specification got a reading guide, a table of its constructs and an example for each directive.

Package change

The only published change is a patch to @doc-kit/generator-react. Islands that hydrate on interaction (code tabs, copy buttons) used to swallow the click or tap that started their hydration, so you had to press twice. The runtime now holds those presses and replays them once the island is ready, covered by presses.test.mjs.

Follow-ups

The benchmarks get re-run once perf: keep memory use down at low thread counts #1179 and chore(core): find input files with node:fs globSync #1180 land.
The unrelated fixes I found along the way go in their own PRs: stability-index linking (until then, the first Stability: N in a code example gets linked), sidebar reveal, backticks in page titles, search on nested 404s, navbar activeOn and search labels.
doc-kit preview is documented already, pending feat: add preview command #1082.
The home page lands in llms-full.txt and index.json as raw MDX, and doc-kit hides the copy button on one-line code blocks, so the install commands don't get one. Both need small fixes in the generators.
The legacy generators have a few bugs I'll open issues for: the version links on all.html miss a slash, legacy-html-all and legacy-json-all can change order between runs, and --git-ref doesn't reach legacy-html.
The specification stated three rules as both MUST and SHOULD (§3.1, §3.2, §11.6); they now say SHOULD, which matches the parser. It's a normative change, so I'd love a second pair of eyes there.

Validation

node --run format:check, node --run lint and node --run test (753 tests) pass, and a production build of the site (41 pages) has no broken links or missing assets.

The home page:

The whole home page, dark, light and on a phone

The docs, in both themes, on a phone and with search open:

Dark	Light

The illustrations, each on the page it explains (Getting started, Writing documentation, Customizing the site, Creating generators and Generators):

Related Issues

None.

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

Rewrites every page, package README and generator README for clarity and accuracy against the code, and splits the docs into guides, which teach a task with one running example, and reference pages, which list every option. Guides link to the reference instead of repeating it. - `index.md` becomes `introduction.md`, and a new guide covers documenting TypeScript and JSDoc with `@doc-kit/typedoc`. - Every generator page follows one layout: what it makes, what it reads and writes, usage, options, then details. - The specification gains a reading guide, a table of its constructs and examples for every directive, and resolves rules it stated as both MUST and SHOULD. - Code examples whose Markdown bullets the formatter rewrote (the changelog, `index.md` and `llms.txt` samples) are plain text again, so they show what doc-kit actually reads and writes. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

Gives doc-kit's own site a theme of its own, built entirely through the html generator's public extension points (theme slots, components, stylesheets, a template and rehype plugins), so the site doubles as an example of customizing doc-kit. - A home page that shows what doc-kit does: an isometric hero, the sources and outputs of one kittens module, the worker pool building a site, benchmarks and a getting-started path. Its canvases are islands that respect reduced motion. - A neutral palette over `@node-core/ui-components`, with light and dark themes, a cat logo, Inter, and styled search and theme menus. - Five isometric illustrations in the guides, inlined as SVG so they follow the color scheme, each on the one page it explains. - The sidebar groups guides, reference, generators and packages; the build script also takes the site's own pages from `www/pages`, and leaves out the legacy-format generators and the generators documented on another generator's page. Redirects send their old URLs to the sections that now cover them. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

Islands that hydrate on interaction, such as code tabs and copy buttons, start loading their component on pointerover, focusin or touchstart. The click or tap that follows lands before the component exists, so it did nothing and had to be repeated. The runtime now holds an interaction island's presses until it is hydrated, then dispatches them again, each once the innermost island around it is ready. The site's redesign surfaced this on every code block. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

vercel · 2026-10-27T14:56:31Z

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

Project	Deployment	Actions	Updated
api-docs-tooling	Ready	Preview	Oct 27, 2026 6:30pm UTC

codecov · 2026-10-27T14:57:52Z

Codecov Report

❌ Patch coverage is 0% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.41%. Comparing base (0321911) to head (e5b8ad1).

Files with missing lines	Patch %	Lines
scripts/build-docs-content.mjs	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1192      +/-   ##
==========================================
- Coverage   93.41%   93.41%   -0.01%     
==========================================
  Files         278      278              
  Lines       27840    27841       +1     
  Branches     2790     2790              
==========================================
  Hits        26008    26008              
- Misses       1810     1811       +1     
  Partials       22       22

☔ 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-10-27T14:58:13Z