Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
33c10e7
docs: rewrite and restructure the documentation
ovflowd Oct 27, 2026
3261124
feat(www): redesign doc-kit.nodejs.org
ovflowd Oct 27, 2026
a404412
fix(react): replay the press that hydrates an island
ovflowd Oct 27, 2026
7a853ec
refactor(www): skip comments instead of stripping them when inlining …
ovflowd Oct 27, 2026
0bdd6bb
refactor(react): keep the press events with the other UI constants
ovflowd Oct 27, 2026
6835ddf
chore(www): make the site its own workspace package
ovflowd Oct 27, 2026
4c571b6
chore(www): add the source of the social preview image
ovflowd Oct 27, 2026
b76d1bc
feat(www): make the benchmarks reproducible
ovflowd Oct 27, 2026
b7992df
docs: give every generator its own page again
ovflowd Oct 27, 2026
42d666a
feat(www): write the home page in MDX on doc-kit's own code blocks
ovflowd Oct 27, 2026
32fef69
docs: link to one place instead of repeating it
ovflowd Oct 29, 2026
16c9eda
fix(react): scope the heading layout and mark the selected code tab
ovflowd Oct 29, 2026
965c875
refactor(www): drop the workarounds doc-kit no longer needs
ovflowd Oct 29, 2026
cc27b62
feat(www): build the all page and take more from the configuration
ovflowd Oct 29, 2026
81e70af
docs(react): shorten the comment on held presses
ovflowd Oct 29, 2026
a2ff6b2
refactor: move the benchmark to scripts/ and slim it down
ovflowd Oct 29, 2026
22bce64
docs: make the diagrams self-contained and play them once
ovflowd Oct 29, 2026
ea0b9f9
feat(www): draw the home page's animations as SVGs
ovflowd Oct 29, 2026
22c3b2c
refactor(www): keep the home page's main landmark on a div
ovflowd Oct 29, 2026
b968eab
feat(www): polish Kit's head
ovflowd Oct 29, 2026
607ac4e
chore(www): format the social card's source
ovflowd Oct 29, 2026
70fc4db
fix(www): bring back the site and search previews
ovflowd Oct 29, 2026
0bf2a4e
docs: format the guides with oxfmt 0.74
ovflowd Nov 6, 2026
a713a85
fix(react): replay the press that starts an island loading
ovflowd Nov 6, 2026
caa2360
docs: measure the benchmarks again now that #1179 has landed
ovflowd Nov 6, 2026
66d05c4
test: add versioned pageURL tests for canonical function
bmuenzenmeyer Nov 7, 2026
e487647
fix(react): link the release line and the index's directory as canonical
ovflowd Nov 9, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
refactor: move the benchmark to scripts/ and slim it down
`scripts/benchmark.mjs` replaces `www/benchmark.mjs`, without the word
counts and the copy of the site's sources, and builds every Markdown file
in Node.js's `doc/api` instead of leaving `quic.md` out by hand. The home
page's data no longer spells out numbers, and the numbers are refreshed.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
  • Loading branch information
ovflowd committed Nov 17, 2026
commit a2ff6b230c04273f2ea7f3e4cdd3d9cb03a3928b
26 changes: 13 additions & 13 deletions docs/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,33 +54,33 @@ generator reading it is done with it, and the website generator holds one page
per worker, so its memory follows your largest page rather than the size of
the whole site.

Building this site, 40 pages and 50,225 words, with its own
Building this site, 40 pages, with its own
[configuration](https://github.com/nodejs/doc-kit/blob/main/www/doc-kit.config.mjs):

| Targets | Output | Time |
| --------------------------- | ------------------------------------- | ------ |
| `llms-txt` | `llms.txt` | 0.56 s |
| `orama-db` | The search index | 0.61 s |
| `json` | 40 JSON documents | 0.63 s |
| `html` | The site: 40 pages, bundled with Vite | 2.74 s |
| The configuration's targets | All of it, 214 files | 2.94 s |
| `llms-txt` | `llms.txt` | 0.51 s |
| `orama-db` | The search index | 0.55 s |
| `json` | 40 JSON documents | 0.56 s |
| `html` | The site: 40 pages, bundled with Vite | 2.85 s |
| The configuration's targets | All of it, 213 files | 2.90 s |

Most of the website's time is Vite bundling its scripts and styles once, a
cost that doesn't grow with the number of pages. The Node.js v26.12.1 API docs
show how the rest scales, with 70 files and 574,627 words, built with the
show how the rest scales, with 71 files, built with the
configuration of [the Node.js preview site](https://beta.docs.nodejs.org/):

| Targets | Output | Time |
| ----------------------------------------------- | -------------------- | ------ |
| `llms-txt` | `llms.txt` | 2.4 s |
| `orama-db` | The search index | 2.8 s |
| `json` | 70 JSON documents | 2.9 s |
| `section-pages` | The site: 781 pages | 10.2 s |
| `section-pages`, `json`, `llms-txt`, `orama-db` | All of it, 923 files | 10.8 s |
| `llms-txt` | `llms.txt` | 2.2 s |
| `orama-db` | The search index | 2.6 s |
| `json` | 71 JSON documents | 2.6 s |
| `section-pages` | The site: 794 pages | 9.7 s |
| `section-pages`, `json`, `llms-txt`, `orama-db` | All of it, 937 files | 10.1 s |

Each time is the median of five clean builds on an AMD Ryzen 9 8945HX
(32 threads, 4 used by doc-kit) with Node.js 24.18 and doc-kit
`b413a20`. To measure them on your machine, run this from a doc-kit
`12a5473`. To measure them on your machine, run this from a doc-kit
checkout with its dependencies installed. It checks out the Node.js docs
once, builds both sites, and writes the results to
`www/theme/benchmarks.json`, which the home page reads:
Expand Down
217 changes: 217 additions & 0 deletions scripts/benchmark.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,217 @@
// Times the builds the website's home page quotes, and writes them to
// `www/theme/benchmarks.json`: the website itself, and a Node.js release's API
// docs with the Node.js preview site's configuration (`beta/`). Each target is
// built on its own, then all of them in one run, from an empty output
// directory, and the median of the runs is kept.
//
// node scripts/benchmark.mjs [--runs 5] [--node v26.12.1]

import { execFileSync, spawnSync } from 'node:child_process';
import { existsSync } from 'node:fs';
import { glob, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { cpus, tmpdir } from 'node:os';
import { join } from 'node:path';
import { parseArgs } from 'node:util';
import { gzipSync } from 'node:zlib';

const ROOT = join(import.meta.dirname, '..');
const CLI = join(ROOT, 'packages', 'cli', 'bin', 'cli.mjs');
const CACHE = join(ROOT, 'node_modules', '.cache', 'doc-kit-benchmark');

const { values } = parseArgs({
options: {
runs: { type: 'string', default: '5' },
node: { type: 'string' },
},
});

const git = (...args) =>
execFileSync('git', args, { cwd: ROOT, encoding: 'utf-8' }).trim();

const median = numbers => {
const sorted = numbers.toSorted((a, b) => a - b);
const middle = sorted.length >> 1;

return sorted.length % 2
? sorted[middle]
: (sorted[middle - 1] + sorted[middle]) / 2;
};

const filesIn = async (dir, pattern = '**/*') =>
Array.fromAsync(glob(pattern, { cwd: dir, withFileTypes: true }))
.then(entries => entries.filter(entry => entry.isFile()))
.then(entries => entries.map(entry => join(entry.parentPath, entry.name)));

/**
* The gzipped size, in kB, of the scripts a built `index.html` loads.
*
* @param {string} output
*/
const clientKilobytes = async output => {
const html = await readFile(join(output, 'index.html'), 'utf-8');
const scripts = html.matchAll(/<script[^>]+src="?([^"\s>]+)/g);
let bytes = 0;

for (const [, src] of scripts) {
bytes += gzipSync(await readFile(join(output, src))).length;
}

return Math.round(bytes / 1024);
};

/**
* Builds each target on its own and then all of them together, `--runs`
* times each, and counts what the last run of each wrote.
*
* @param {Array<string>} common Arguments every run shares
* @param {Record<string, Array<string>>} targets Each target's arguments
*/
const measure = async (common, targets) => {
const results = {};

targets.all = Object.values(targets).flat();

for (const [name, args] of Object.entries(targets)) {
const times = [];
let output;

for (let run = 0; run < Number(values.runs); run++) {
await rm(output ?? '', { recursive: true, force: true });
output = await mkdtemp(join(tmpdir(), 'doc-kit-benchmark-'));

const start = performance.now();
const { status, stderr } = spawnSync(
process.execPath,
[
CLI,
'generate',
...common,
...args,
'-o',
output,
'--log-level',
'error',
],
{ cwd: ROOT, encoding: 'utf-8' }
);

if (status !== 0) {
throw new Error(`generate ${args.join(' ')} failed:\n${stderr}`);
}

times.push((performance.now() - start) / 1000);
}

const written = await filesIn(output);

results[name] = {
seconds: Number(median(times).toFixed(2)),
files: written.length,
pages: written.filter(path => path.endsWith('.html')).length,
};

if (existsSync(join(output, 'index.html'))) {
results[name].clientKilobytes = await clientKilobytes(output);
}

await rm(output, { recursive: true, force: true });
console.log(`${name}: ${results[name].seconds} s`);
}

return results;
};

// The website, from the sources `build-docs-content.mjs` assembles
execFileSync(process.execPath, ['scripts/build-docs-content.mjs'], {
cwd: ROOT,
});

const site = {
pages: (await filesIn(join(ROOT, 'www', 'content'), '**/*.{md,mdx}')).length,
results: await measure(
['--config-file', join(ROOT, 'www', 'doc-kit.config.mjs')],
{
'llms-txt': ['-t', 'llms-txt'],
'orama-db': ['-t', 'orama-db'],
json: ['-t', 'json'],
html: ['-t', 'html'],
}
),
};

// The latest Node.js release, or the one asked for, checked out once
const tag =
values.node ??
git(
'ls-remote',
'--tags',
'--refs',
'--sort=-v:refname',
'https://github.com/nodejs/node.git',
'v*'
)
.split('\n')
.map(line => line.split('refs/tags/')[1])
.find(name => !name.includes('-'));

const checkout = join(CACHE, `node-${tag}`);

if (!existsSync(checkout)) {
git(
'clone',
'-q',
'--depth',
'1',
'--branch',
tag,
'--filter=blob:none',
'--sparse',
'https://github.com/nodejs/node.git',
checkout
);
git('-C', checkout, 'sparse-checkout', 'set', 'doc', 'lib');
}

const api = join(checkout, 'doc', 'api');

const node = {
version: tag,
files: (await filesIn(api, '*.md')).length,
results: await measure(
[
'--config-file',
join(ROOT, 'beta', 'doc-kit.config.mjs'),
'-i',
`${api}/*.md`,
'--type-map',
join(checkout, 'doc', 'type-map.json'),
'-c',
join(checkout, 'CHANGELOG.md'),
'-v',
tag,
],
{
'llms-txt': ['-t', 'llms-txt'],
'orama-db': ['-t', 'orama-db'],
json: ['-t', 'json'],
'section-pages': ['-t', 'section-pages'],
}
),
};

await writeFile(
join(ROOT, 'www', 'theme', 'benchmarks.json'),
`${JSON.stringify(
{
machine: `${cpus()[0]
.model.replace(/ with .*$/, '')
.trim()} with Node.js ${process.versions.node}`,
commit: git('rev-parse', '--short', 'HEAD'),
runs: Number(values.runs),
site,
node,
},
null,
2
)}\n`
);
Loading