perf: stop minifying HTML

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 HTML by default.
The pages are now written as rendered, and `@swc/html-wasm` is gone,
along with `@doc-kit/core/utils/html-minifier.mjs`. `minify` still
minifies scripts, styles and JSON, and the publishing docs now explain
how to serve the pages compressed.

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

.github/dependabot.yml

@@ -73,7 +73,6 @@ updates:
           - 'recma-*'
       compiling:
         patterns:
-          - '@swc/html-wasm'
           - '@rollup/*'
           - 'rolldown'
           - 'lightningcss-wasm'

docs/configuration.md

@@ -109,7 +109,10 @@ 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 JSON, scripts, and styles. HTML is
+  written as is: serve it compressed instead (see
+  [Compress the pages](./publishing.md#compress-the-pages)). **Default:**
+  `true`.
 - `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,24 @@ 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 writes HTML as rendered, without minifying it. Served compressed (gzip
+or brotli), as hosts do, pages shrink to a fraction of their size, which
+minifying them would barely improve on.
+
+Cloudflare, Vercel, Netlify, and GitHub Pages compress HTML on their own, with
+nothing to configure, 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/package.json

@@ -53,7 +53,6 @@
   ],
   "dependencies": {
     "@node-core/rehype-shiki": "^1.5.1",
-    "@swc/html-wasm": "^1.16.2",
     "@swc/wasm": "^1.15.46",
     "acorn": "^8.17.0",
     "cosmiconfig": "^9.0.2",

packages/core/src/utils/html-minifier.mjs

@@ -7,7 +7,5 @@ The `legacy-html-all` generator creates a single `all.html` file containing all
 - `output` {string} The directory where `all.html` will be written.
 - `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`.
 - `version` {Object} Version object containing version information. Inherited
   from `global`. **Default:** `process.version`.

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

@@ -4,7 +4,6 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import getConfig from '@doc-kit/core/utils/configuration/index.mjs';
-import { minifyHTML } from '@doc-kit/core/utils/html-minifier.mjs';
 import { getProcessor } from '@doc-kit/core/utils/markdown/processor.mjs';
 
 import { replaceTemplateValues } from '../legacy-html/utils/replaceTemplateValues.mjs';
@@ -56,15 +55,11 @@ export async function generate(input) {
     content: aggregatedContent,
   };
 
-  let result = replaceTemplateValues(apiTemplate, templateValues, config, {
+  const result = replaceTemplateValues(apiTemplate, templateValues, config, {
     skipGitHub: true,
     skipGtocPicker: true,
   });
 
-  if (config.minify) {
-    result = await minifyHTML(result);
-  }
-
   if (config.output) {
     await writeFile(join(config.output, 'all.html'), result);
   }

packages/node-legacy/src/legacy-html-all/generate.mjs

@@ -17,5 +17,3 @@ The `legacy-html` generator creates legacy HTML documentation pages for Node.js
   **Default:** `'${GITHUB_EDIT_URL}/doc/api{path}.md'`.
 - `index` {Array} Array of `{ api, section }` objects defining the
   documentation structure.
-- `minify` {boolean} Whether to minify the output HTML. Inherited from
-  `global`. **Default:** `true`.

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

@@ -6,7 +6,6 @@ import { basename, join } from 'node:path';
 import getConfig from '@doc-kit/core/utils/configuration/index.mjs';
 import { writeFile } from '@doc-kit/core/utils/file.mjs';
 import { groupNodesByModule } from '@doc-kit/core/utils/generators.mjs';
-import { minifyHTML } from '@doc-kit/core/utils/html-minifier.mjs';
 import { getProcessor } from '@doc-kit/core/utils/markdown/processor.mjs';
 
 import buildContent from './utils/buildContent.mjs';
@@ -124,11 +123,7 @@ export async function* generate(input, worker) {
     // Write files for this chunk in the generate method (main thread)
     if (config.output) {
       for (const template of chunkResult) {
-        let result = replaceTemplateValues(apiTemplate, template, config);
-
-        if (config.minify) {
-          result = await minifyHTML(result);
-        }
+        const result = replaceTemplateValues(apiTemplate, template, config);
 
         await writeFile(join(config.output, `${template.api}.html`), result);
       }

packages/node-legacy/src/legacy-html/generate.mjs

@@ -9,7 +9,7 @@ output-only and does not return an in-memory copy of its HTML or CSS.
 The site is built in pieces that are each as small as they can be. The bundler
 builds the component library once and the client assets once. Each page's
 program is then compiled — JSX to a plain module — and the worker pool imports,
-renders, templates, minifies and writes the pages one at a time, so memory
+renders, templates and writes the pages one at a time, so memory
 scales with the largest page rather than with the site. `all.html` is assembled
 from the module pages' compiled content rather than built again from scratch.
 
@@ -509,9 +509,8 @@ Since the template supports arbitrary JS expressions, you can use conditionals a
 <title>${title}</title> ${assets}
 ```
 
-The populated page is the final HTML: it is minified when `minify` is set and
-written as is. Put `${assets}` in the `<head>`, or the page loads no script and
-no stylesheet.
+The populated page is the final HTML, written as is. Put `${assets}` in the
+`<head>`, or the page loads no script and no stylesheet.
 
 ## Client-side navigation