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

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

PREVIEW: https://feat-site-redesign-doc-kit.nodejs.workers.dev/

Description

This PR redesigns doc-kit.nodejs.org: a new theme and home page, illustrations for the guides, and a pass over the docs so every topic lives on one page. The whole site is built with doc-kit's own extension points (theme slots, components, stylesheets and a custom template), 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: the sources and outputs of one kittens module, the worker pool building a site, benchmarks and a getting-started path. It's MDX (www/pages/index.mdx) with plain fenced code blocks, so the samples get doc-kit's own highlighting, code boxes, tabs and copy buttons.
The hero and the pipeline are animated SVGs in www/public/home/, with a narrower drawing of each for phones. They come from the same build simulation and layout the canvas version had, so they show the same run, but the site doesn't ship any animation code anymore.
A neutral theme over @node-core/ui-components, light and dark, with Inter and styled search and theme menus. Kit (the cat) and the headline are placeholders until we settle them in Proposal: Kit, doc-kit's mascot, and a tagline for the site #1197.
Five illustrations in the guides, each on the page it explains. They're self-contained SVGs with their own styles, colors and fonts, so they work as plain images here and on GitHub, follow the theme switch, and play once before stopping on the finished picture.
www is a private workspace package (@doc-kit/www) with the source of the social card (node --run og renders www/og/og.html). The numbers on the home page come from node scripts/benchmark.mjs: this site's 40 pages build in 2.9 s, and the Node.js v26.12.1 API docs in 10.1 s.

Documentation

Every page and README was checked against the code, and each topic lives in one place that the others link to: flags in the CLI page, global options in Configuration, the theme reference in the html generator's README, and so on.
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, including json-all, json-simple, llms-txt-full and the legacy ones. The overview links all of them, and the sidebar keeps to the main ones.
The specification is the same as on main.

Package changes

Two patches 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.
In the default theme, the heading layout only applies to API entry headings now, not to any div with a heading inside <main>. The selected code tab stands out again (the neutral palette made it blend in) and tabs wrap on narrow screens. The default template also gets a canonical link, built from pageURL, and theme-color.

Follow-ups

The benchmarks get re-run once perf: keep memory use down at low thread counts #1179 lands.
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 and search labels, search on nested 404s and navbar activeOn.
Renaming the generate workflow's web target to html in its own PR, since PR runs look up main's artifact by that name.
ui-components writes ⌘ K on every platform and leaves a focus ring on the theme toggle after its menu closes. Those fixes go in nodejs.org.
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.
A few bugs I ran into: man-page drops the last environment variable when its section ends the page (man-page: drops the last environment variable when the section ends the page #1198), addon-verify re-indents the test.js it writes (addon-verify: re-indents the test.js it generates #1199), the sitemap lists the index twice (sitemap: lists the index page twice when index.md is an input #1200) and a custom html bundler fails with more than one thread (html: a custom bundler fails with DataCloneError unless threads is 1 #1201). I'll also open issues for all.html's version links missing a slash and --git-ref not reaching legacy-html.

Validation

node --run format:check, node --run lint and node --run test (778 tests) pass, and a production build of the site has no missing assets. The link check only flags two things that are broken on main too: the spec's own #722-level-1--experimental anchor, and the relative links of the contributing pages once they're inlined into all.html.

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

Refs #1197

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.

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 29, 2026 8:46pm UTC

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

Codecov Report

❌ Patch coverage is 17.66917% with 219 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.86%. Comparing base (854a944) to head (e0d7ced).
⚠️ Report is 1 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1192      +/-   ##
==========================================
- Coverage   93.42%   92.86%   -0.57%     
==========================================
  Files         286      288       +2     
  Lines       28502    28840     +338     
  Branches     2870     2890      +20     
==========================================
+ Hits        26628    26782     +154     
- Misses       1852     2036     +184     
  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