perf: don't minify by default

The HTML generators minified every page with SWC's HTML minifier,
compiled to WASM. Its memory grows to about twelve times the biggest
page it is given, and is never returned: each thread rendering pages
kept it until it ended, and on Node.js 24, the worker that minified the
Node.js docs' 33MB `all.html` collected garbage on nearly every
allocation from then on, as V8 found that memory too large for its
heap limit. Minifying also took a fifth of the build's CPU.

For that, the Node.js docs' pages were 5.9% smaller, but only 3.2%
once gzipped and 2.1% with brotli, which is how hosts serve them:
Cloudflare, Vercel, Netlify and GitHub Pages compress by default. So
`minify` now defaults to `false`, the minifier is only loaded when it is
enabled, and the publishing docs explain how to serve the output
compressed. The `html` generator's scripts and styles stay minified,
unless `vite.build.minify` says otherwise.

On Node core's build with 4 threads on Node.js 26, the build takes 7.7s
instead of 10.5s and peaks at ~1.68GB instead of ~2.12GB; with one
thread, 15.2s instead of 22.5s. On Node.js 24, 7.9s instead of 51.7s.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: ovflowd

docs/configuration.md

@@ -109,7 +109,7 @@ Everything under the `global` key applies to every generator:
   logos, and templated text. Defaults to the `name` in your `package.json`.
 - `version` {string|SemVer} Documentation version. **Default:**
   `process.version`.
-- `minify` {boolean} Whether to minify output. **Default:** `true`.
+- `minify` {boolean} Whether to minify output. **Default:** `false`.
 - `repository` {string} GitHub repository in `owner/repo` format; without
   one, repository UI is omitted.
 - `ref` {string} Git reference (branch, tag, or commit SHA). **Default:**

docs/publishing.md

@@ -56,6 +56,22 @@ costs a request per asset each time a new tab opens the site. On Vercel:
 Within a visit, moving between pages loads no assets at all: the site
 navigates client-side, swapping in the next page's content.
 
+## Compress the pages
+
+doc-kit doesn't minify its output by default: compressed (gzip or brotli), as
+hosts serve it, it is far smaller than minifying would make it.
+
+Cloudflare, Vercel, Netlify, and GitHub Pages compress on their own, and so
+does `npx serve out`. If you serve the output yourself, turn compression on:
+
+- **nginx:** `gzip on;` compresses HTML; add the other types with
+  `gzip_types text/css application/javascript application/json;`.
+- **Caddy:** `encode zstd gzip`.
+- **Apache:** with `mod_deflate`,
+  `AddOutputFilterByType DEFLATE text/html text/css application/javascript application/json`.
+- **Amazon S3:** serve the bucket through CloudFront, with **Compress objects
+  automatically** on.
+
 ## Tell doc-kit its public URL
 
 Set `baseURL` to where the site will live. Generators that emit absolute

packages/core/src/generators/json-all/README.md

@@ -23,7 +23,7 @@ generator's schema for the documents.
 
 - `output` {string} The directory where `all.json` will be written.
 - `minify` {boolean} Whether to minify the output. Inherited from `global`.
-  **Default:** `true`.
+  **Default:** `false`.
 - `index` {Array} The `{ api }` objects defining the document order. Inherited
   from `global`.
 - `schemaURL` {string} Where the bundle's schema is published.

packages/core/src/generators/json-simple/README.md

@@ -6,4 +6,4 @@ The `json-simple` generator creates a simplified JSON version of the API documen
 
 - `output` {string} The directory where `api-docs.json` will be written.
 - `minify` {boolean} Whether to minify the output JSON. Inherited from
-  `global`. **Default:** `true`.
+  `global`. **Default:** `false`.

packages/core/src/generators/json/README.md

@@ -18,7 +18,7 @@ Files keep the input's directory layout: `doc/api/some/fs.md` becomes `out/some/
 
 - `output` {string} The directory to write the documents to.
 - `minify` {boolean} Whether to minify the output. Inherited from `global`.
-  **Default:** `true`.
+  **Default:** `false`.
 - `repository` {string} The `owner/name` repository source links resolve
   against. Inherited from `global`; without one, `sourceLink.url` is `null`.
 - `schemaURL` {string} Where the schema is published. `{schemaVersion}` is

packages/core/src/utils/configuration/index.mjs

@@ -62,7 +62,7 @@ export const getDefaultConfig = (generators, config) =>
       global: {
         project: detectProject() ?? 'API Docs',
         version: process.version,
-        minify: true,
+        minify: false,
         ref: 'HEAD',
         // Without release history there is nothing to build a version picker
         // from, so generators render single-version output.

packages/node-legacy/src/legacy-html-all/README.md

@@ -8,6 +8,6 @@ The `legacy-html-all` generator creates a single `all.html` file containing all
 - `templatePath` {string} Path to the HTML template file. Inherited from
   `legacy-html`. **Default:** `'template.html'`.
 - `minify` {boolean} Whether to minify the output HTML. Inherited from
-  `global`. **Default:** `true`.
+  `global`. **Default:** `false`.
 - `version` {Object} Version object containing version information. Inherited
   from `global`. **Default:** `process.version`.

packages/node-legacy/src/legacy-html/README.md

@@ -18,4 +18,4 @@ The `legacy-html` generator creates legacy HTML documentation pages for Node.js
 - `index` {Array} Array of `{ api, section }` objects defining the
   documentation structure.
 - `minify` {boolean} Whether to minify the output HTML. Inherited from
-  `global`. **Default:** `true`.
+  `global`. **Default:** `false`.

packages/node/src/api-links/README.md

@@ -8,4 +8,4 @@ The `api-links` generator creates a mapping of publicly accessible functions to
 - `sourceURL` {string} URL template for linking to source files.
   **Default:** `'${GITHUB_BLOB_URL}lib/{fileName}'`.
 - `minify` {boolean} Whether to minify the output JSON. Inherited from
-  `global`. **Default:** `true`.
+  `global`. **Default:** `false`.

packages/react/src/html/__tests__/generate.test.mjs

@@ -102,21 +102,21 @@ describe('web generate', () => {
     ]);
 
     assert.match(fsHTML, /View As/);
-    assert.match(fsHTML, /href=fs\.json/);
-    assert.match(fsHTML, /href=fs\.md/);
+    assert.match(fsHTML, /href="fs\.json"/);
+    assert.match(fsHTML, /href="fs\.md"/);
     assert.doesNotMatch(notFoundHTML, /View As/);
     // Assets resolve from the page: relative for real pages, from the root
     // for synthetic ones, which are served at any path
-    assert.match(fsHTML, /src=\.\.\/assets\/client-[^ ]+\.js/);
-    assert.match(fsHTML, /href=\.\.\/assets\/[^ ]+\.css/);
-    assert.match(notFoundHTML, /src=\/assets\/client-[^ ]+\.js/);
-    assert.match(fsHTML, /on:idle[^>]*data-island-name=SearchBox/);
+    assert.match(fsHTML, /src="\.\.\/assets\/client-[^"]+\.js"/);
+    assert.match(fsHTML, /href="\.\.\/assets\/[^"]+\.css"/);
+    assert.match(notFoundHTML, /src="\/assets\/client-[^"]+\.js"/);
+    assert.match(fsHTML, /on:idle[^>]*data-island-name="SearchBox"/);
     // The manifest the asset tags were read from does not ship
     assert.equal((await readdir(output)).includes('.vite'), false);
 
     // Fonts are hashed like every other asset, and preloaded from where the
     // bundler actually wrote them
-    const fonts = [...fsHTML.matchAll(/href=\.\.\/(assets\/[^ ]+\.woff2)/g)];
+    const fonts = [...fsHTML.matchAll(/href="\.\.\/(assets\/[^"]+\.woff2)"/g)];
     const written = await readdir(join(output, 'assets'));
 
     assert.strictEqual(fonts.length, FONTS.length);
@@ -150,7 +150,7 @@ describe('web generate', () => {
     assert.match(html, /File system body[\s\S]*Zlib body/);
     assert.doesNotMatch(html, /Index body/);
     // Their tables of contents, concatenated
-    assert.match(html, /href=#fs[\s\S]*href=#zlib/);
+    assert.match(html, /href="#fs"[\s\S]*href="#zlib"/);
     assert.doesNotMatch(html, /View As/);
   });
 
@@ -209,30 +209,30 @@ describe('web generate', () => {
     ]);
 
     // Assets and module files resolve from the nested directory
-    assert.match(readFileHTML, /src=\.\.\/assets\//);
-    assert.match(readFileHTML, /href=\.\.\/fs\.json/);
-    assert.match(readFileHTML, /href=\.\.\/fs\.html#fsreadfile/);
+    assert.match(readFileHTML, /src="\.\.\/assets\//);
+    assert.match(readFileHTML, /href="\.\.\/fs\.json"/);
+    assert.match(readFileHTML, /href="\.\.\/fs\.html#fsreadfile"/);
 
     // The sidebar nests the module's sections, repeating the module itself
     assert.match(readFileHTML, /<details[^>]*open/);
     assert.match(
       readFileHTML,
-      /href=\.\.\/fs\.html[^>]*>(<[^>]*>)*File system/
+      /href="\.\.\/fs\.html"[^>]*>(<[^>]*>)*File system/
     );
-    assert.match(readFileHTML, /href=callback-api\.html/);
+    assert.match(readFileHTML, /href="callback-api\.html"/);
 
     // Previous/next step through the module's sections
     assert.match(readFileHTML, /Callback API/);
-    assert.match(readFileHTML, /href=watch\.html/);
+    assert.match(readFileHTML, /href="watch\.html"/);
     assert.match(fsHTML, /Next/);
 
     // Links were re-targeted for the chunk page
-    assert.match(readFileHTML, /href=watch\.html#fswatch/);
-    assert.match(readFileHTML, /href=\.\.\/net\.html/);
+    assert.match(readFileHTML, /href="watch\.html#fswatch"/);
+    assert.match(readFileHTML, /href="\.\.\/net\.html"/);
 
     // The full page is untouched, and lists sections in its own sidebar
-    assert.match(fsHTML, /href=fs\.json/);
-    assert.match(fsHTML, /href=fs\/readFile\.html/);
+    assert.match(fsHTML, /href="fs\.json"/);
+    assert.match(fsHTML, /href="fs\/readFile\.html"/);
   });
 
   it('renders the configurable head without hardcoded defaults', async context => {
@@ -252,10 +252,10 @@ describe('web generate', () => {
 
     assert.match(html, /Custom project docs/);
     assert.match(html, /https:\/\/example\.com\/og\.png/);
-    assert.match(html, /href=https:\/\/example\.com\/favicon\.ico/);
-    assert.match(html, /content=#abcdef/);
+    assert.match(html, /href="https:\/\/example\.com\/favicon\.ico"/);
+    assert.match(html, /content="#abcdef"/);
     assert.doesNotMatch(html, /nodejs\.org/);
-    assert.match(html, /property=og:type content=website/);
+    assert.match(html, /property="og:type" content="website"/);
   });
 
   it('uses the base URL for absolute client assets', async context => {
@@ -268,8 +268,8 @@ describe('web generate', () => {
     await generate([toPage(content)]);
     const html = await readFile(join(output, '404.html'), 'utf8');
 
-    assert.match(html, /src=https:\/\/example\.com\/docs\/assets\//);
-    assert.match(html, /href=https:\/\/example\.com\/docs\/assets\//);
+    assert.match(html, /src="https:\/\/example\.com\/docs\/assets\//);
+    assert.match(html, /href="https:\/\/example\.com\/docs\/assets\//);
   });
 
   it('applies configured Vite plugins to the client build', async context => {
@@ -367,18 +367,18 @@ describe('web generate', () => {
     assert.match(html, /<article data-custom-ssr>fs:1<\/article>/);
     assert.match(
       html,
-      /<script type=module crossorigin src=\.\/custom\/index\.js>/
+      /<script type="module" crossorigin src="\.\/custom\/index\.js">/
     );
     assert.match(html, /data-router/);
     // The adapter reported no fonts, so there are none to preload
-    assert.doesNotMatch(html, /as=font/);
+    assert.doesNotMatch(html, /as="font"/);
     assert.match(
       html,
-      /<link rel=modulepreload crossorigin href=\.\/custom\/shared\.js>/
+      /<link rel="modulepreload" crossorigin href="\.\/custom\/shared\.js" \/>/
     );
     assert.match(
       html,
-      /<link rel=stylesheet crossorigin href=\.\/custom\/index\.css>/
+      /<link rel="stylesheet" crossorigin href="\.\/custom\/index\.css" \/>/
     );
     assert.deepStrictEqual(calls, ['server', 'client', 'compile']);
   });