doc: move to redesign

.github/dependabot.yml

@@ -58,7 +58,8 @@ updates:
       semver-minor-days: 5
       semver-patch-days: 5
       exclude:
-        - '@node-core/doc-kit'
+        - '@doc-kit/*'
+        - '@node-core/*'
     commit-message:
       prefix: tools
     open-pull-requests-limit: 10

.github/workflows/build-tarball.yml

@@ -67,6 +67,7 @@ env:
   PYTHON_VERSION: '3.15'
   FLAKY_TESTS: keep_retrying
   CLANG_VERSION: '19'
+  NODE_VERSION: lts/*
 
 permissions:
   contents: read
@@ -84,6 +85,10 @@ jobs:
         with:
           python-version: ${{ env.PYTHON_VERSION }}
           allow-prereleases: true
+      - name: Use Node.js ${{ env.NODE_VERSION }}
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
       - name: Make tarball
         run: |
           export DISTTYPE=nightly

Makefile

@@ -402,7 +402,12 @@ ifeq ($(OSTYPE),os400)
 DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp
 endif
 
-DOC_KIT ?= tools/doc/node_modules/@node-core/doc-kit/bin/cli.mjs
+DOC_KIT ?= tools/doc/node_modules/@doc-kit/cli/bin/cli.mjs
+ifeq ($(V),1)
+DOC_KIT_LOG_LEVEL ?= debug
+else
+DOC_KIT_LOG_LEVEL ?= info
+endif
 
 node_use_openssl_and_icu = $(call available-node,"-p" \
 			 "process.versions.openssl != undefined && process.versions.icu != undefined")
@@ -886,8 +891,10 @@ out/doc/api: doc/api
 	mkdir -p $@
 	cp -r doc/api out/doc
 
-# Generate all doc files (individual and all.html/all.json) in a single doc-kit call
-# Using grouped targets (&:) so Make knows one command produces all outputs
+# Generate all doc files (individual and all.html/all.json) in a single doc-kit call.
+# A stamp tells Make that one command produces them all; a grouped target (&:)
+# needs GNU Make 4.3, and older ones (4.2.1 on RHEL 8) rerun the whole build for
+# every output that's still missing.
 ifeq ($(OSTYPE),aix)
 # TODO(@nodejs/web-infra): AIX is currently hanging during HTML minification
 $(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json:
@@ -902,23 +909,23 @@ else ifeq ($(ARCHTYPE),riscv64)
 $(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json:
 	@echo "Skipping $@ (not currently supported by $(DESTCPU) machines)"
 else
-$(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json &: $(apidoc_sources) tools/doc/node_modules | out/doc/api
+out/doc/.docbuildstamp: $(apidoc_sources) tools/doc/node_modules | out/doc/api
 	@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
 		echo "Skipping $@ (no crypto and/or no ICU)"; \
 	else \
 		$(call available-node, \
 			$(DOC_KIT) generate \
-			-t legacy-html-all \
-			-t legacy-json-all \
-			-i doc/api/*.md \
+			--log-level $(DOC_KIT_LOG_LEVEL) \
+			--config-file tools/doc/web.doc-kit.config.mjs \
 			--ignore $(skip_apidoc_files) \
 			-o out/doc/api \
-			-c ./CHANGELOG.md \
 			-v $(VERSION) \
-			--index doc/api/index.md \
-			--type-map doc/type-map.json \
+			$(if $(JOBS),-p $(JOBS)) \
 		) \
 	fi
+	@touch $@
+
+$(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json: out/doc/.docbuildstamp
 endif
 
 out/doc/llms.txt: $(apidoc_sources) tools/doc/node_modules | out/doc
@@ -927,13 +934,12 @@ out/doc/llms.txt: $(apidoc_sources) tools/doc/node_modules | out/doc
 	else \
 		$(call available-node, \
 			$(DOC_KIT) generate \
-			-t llms-txt \
-			-i doc/api/*.md \
+			--log-level $(DOC_KIT_LOG_LEVEL) \
+			--config-file tools/doc/web.doc-kit.config.mjs \
 			--ignore $(skip_apidoc_files) \
+			-t llms-txt \
 			-o $(@D) \
-			-c ./CHANGELOG.md \
 			-v $(VERSION) \
-			--type-map doc/type-map.json \
 		) \
 	fi
 
@@ -943,12 +949,10 @@ out/doc/apilinks.json: $(wildcard lib/*.js) tools/doc/node_modules | out/doc
 	else \
 		$(call available-node, \
 			$(DOC_KIT) generate \
-			-t api-links \
-			-i lib/*.js \
+			--log-level $(DOC_KIT_LOG_LEVEL) \
+			--config-file tools/doc/api-links.doc-kit.config.mjs \
 			-o $(@D) \
-			-c ./CHANGELOG.md \
 			-v $(VERSION) \
-			--type-map doc/type-map.json \
 		) \
 	fi
 
@@ -962,6 +966,7 @@ node.1: doc/api/cli.md tools/doc/node_modules
 	else \
 		$(call available-node, \
 			$(DOC_KIT) generate \
+			--log-level $(DOC_KIT_LOG_LEVEL) \
 			-v $(VERSION) \
 			--config-file tools/doc/man-page.doc-kit.config.mjs \
 			-o doc \
@@ -1505,6 +1510,7 @@ tools/.manpagelintstamp: doc/node.1 doc/api/cli.md tools/doc/node_modules
 		$(RM) -r tools/doc/.manpagecheck && \
 		$(call available-node, \
 			$(DOC_KIT) generate \
+			--log-level $(DOC_KIT_LOG_LEVEL) \
 			-v $(VERSION) \
 			--config-file tools/doc/man-page.doc-kit.config.mjs \
 		) \

doc/node.1

@@ -1,9 +1,9 @@
 .\"
-.\" This file was generated automatically by the @node-core/doc-kit tool.
+.\" This file was generated automatically by Node.js's doc-kit tool.
 .\" Please do not edit this file manually. Make any updates to cli.md
 .\" and regenerate the file afterward.
 .\"
-.\" To regenerate this file, run `make doc/node.1`.
+.\" To regenerate this file, run `make node.1`.
 .\"
 .\"======================================================================
 .Dd $Mdocdate$
@@ -274,7 +274,7 @@ Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --a
 .It Fl -allow-openssl-store
 When using the Permission Model, the process will not be able to use
 OpenSSL STORE loaders by default, for example to load a private key from a
-\fB<URL>\fR passed to \fBcrypto.createPrivateKey()\fR. Attempts to do so will throw
+\fB{URL}\fR passed to \fBcrypto.createPrivateKey()\fR. Attempts to do so will throw
 an \fBERR_ACCESS_DENIED\fR unless the user explicitly passes the
 \fB--allow-openssl-store\fR flag. This permission can be dropped at runtime via
 \fBpermission.drop()\fR.
@@ -452,11 +452,11 @@ creation behavior.
 The following options are currently supported:
 .Bl -bullet
 .It
-\fBbuilder\fR \fB<string>\fR Required. Provides the name to the script that is executed
-before building the snapshot, as if \fB--build-snapshot\fR had been passed
+\fBbuilder\fR \fB{string}\fR Required. Provides the name to the script that is executed
+before building the snapshot, as if \fB--build-snapshot\fR had been passed
 with \fBbuilder\fR as the main script name.
 .It
-\fBwithoutCodeCache\fR \fB<boolean>\fR Optional. Including the code cache reduces the
+\fBwithoutCodeCache\fR \fB{boolean}\fR Optional. Including the code cache reduces the
 time spent on compiling functions included in the snapshot at the expense
 of a bigger snapshot size and potentially breaking portability of the
 snapshot.
@@ -1993,7 +1993,7 @@ Print node's version.
 .It Fl -vfs-load Ns = Ns Ar source
 .Bl -bullet
 .It
-\fBsource\fR \fB<string>\fR A directory or an archive file to mount and run.
+\fBsource\fR \fB{string}\fR A directory or an archive file to mount and run.
 .El
 May be given at most once.
 Mounts \fBsource\fR as a virtual file system (\fBnode:vfs\fR), and runs the entry

test/doctool/test-docs.mjs

@@ -26,17 +26,22 @@ try {
   makefile.close();
 }
 
-const outdir = new URL('../../out/doc/api', import.meta.url);
+const outdir = new URL('../../out/doc/api/', import.meta.url);
 const files = await fs.readdir(outdir);
 
-// Explicitly check for `all.html` and `all.json` as there is no corresponding `all.md` file in `doc/api`.
-assert(files.includes('all.html'), `all.html was not generated (checked ${files})`);
-assert(files.includes('all.json'), `all.json was not generated (checked ${files})`);
+// Explicitly check for `index.html`, `all.html` and `all.json` as there are no
+// corresponding Markdown files in `doc/api`.
+const expectedExtras = ['index.html', 'all.html', 'all.json'];
+for (const name of expectedExtras) {
+  assert(files.includes(name), `${name} was not generated (checked ${files})`);
+}
 
 // Check that every markdown file in `doc/api` was processed.
+const sources = [];
 for await (const file of await fs.opendir(new URL('../../doc/api/', import.meta.url))) {
   // Only expect markdown files in doc/api.
-  assert(path.extname(file.name), 'md');
+  assert.strictEqual(path.extname(file.name), '.md');
+  sources.push(path.basename(file.name, '.md'));
 
   // Always expect markdown file in out/doc/api.
   assert(files.includes(file.name), `${file.name} not found (checked ${files})`);
@@ -48,7 +53,23 @@ for await (const file of await fs.opendir(new URL('../../doc/api/', import.meta.
     assert(!files.includes(htmlFile), `${htmlFile} was unexpectedly generated (checked ${files})`);
     assert(!files.includes(jsonFile), `${jsonFile} was unexpectedly generated (checked ${files})`);
   } else {
-    assert(files.includes(htmlFile), `${htmlFile} was not generated (checked ${files})`);
-    assert(files.includes(jsonFile), `${jsonFile} was not generated (checked ${files})`);
+    for (const generated of [htmlFile, jsonFile]) {
+      assert(files.includes(generated), `${generated} was not generated (checked ${files})`);
+      const { size } = await fs.stat(new URL(generated, outdir));
+      assert.notStrictEqual(size, 0, `${generated} is empty`);
+    }
   }
 }
+
+// Every generated page must come from a current Markdown file, so a stale
+// `out/doc/api` (e.g. from a renamed document) is noticed.
+const expectedPages = ['404.html', 'apilinks.json', ...expectedExtras];
+for (const name of files) {
+  const extension = path.extname(name);
+  if (extension !== '.html' && extension !== '.json') continue;
+  if (expectedPages.includes(name)) continue;
+  assert(
+    sources.includes(path.basename(name, extension)),
+    `Unexpected output: out/doc/api/${name}, remove and rerun.`,
+  );
+}

tools/doc/api-links.doc-kit.config.mjs

@@ -0,0 +1,22 @@
+import { fileURLToPath } from 'node:url';
+
+const root = new URL('../../', import.meta.url);
+
+const fromRoot = (path) =>
+  fileURLToPath(new URL(path, root)).replaceAll('\\', '/');
+
+const urlFromRoot = (path) => new URL(path, root).href;
+
+export default {
+  extends: '@node-core/doc-kit/config',
+
+  target: ['api-links'],
+
+  global: {
+    input: [fromRoot('lib/*.js')],
+    output: fromRoot('out/doc'),
+
+    // Point every loadable URL at its local file so no network request is made.
+    changelog: urlFromRoot('CHANGELOG.md'),
+  },
+};