build, doc: move to redesign

Signed-off-by: Aviv Keller <me@aviv.sh>

Author: avivkeller

.github/dependabot.yml

@@ -53,7 +53,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.14'
   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@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
       - name: Make tarball
         run: |
           export DISTTYPE=nightly

Makefile

@@ -387,7 +387,7 @@ 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
 
 node_use_openssl_and_icu = $(call available-node,"-p" \
 			 "process.versions.openssl != undefined && process.versions.icu != undefined")
@@ -856,7 +856,7 @@ VERSION=v$(RAWVER)
 
 .PHONY: doc-only
 .NOTPARALLEL: doc-only
-doc-only: $(apidoc_dirs) $(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json out/doc/llms.txt out/doc/apilinks.json  ## Builds the docs with the local or the global Node.js binary.
+doc-only: $(apidoc_dirs) $(apidocs_html) $(apidocs_json) out/doc/api/all.json out/doc/apilinks.json  ## Builds the docs with the local or the global Node.js binary.
 
 .PHONY: doc
 doc: $(NODE_EXE) doc-only ## Build Node.js, and then build the documentation with the new binary.
@@ -871,49 +871,16 @@ 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
-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:
-	@echo "Skipping $@ (not currently supported by $(OSTYPE) machines)"
-else ifeq ($(OSTYPE),os400)
-# TODO(@nodejs/web-infra): IBMi is currently hanging during HTML minification
-$(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json:
-	@echo "Skipping $@ (not currently supported by $(OSTYPE) 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
+$(apidocs_html) $(apidocs_json) out/doc/api/all.json &: $(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 \
-			--ignore $(skip_apidoc_files) \
-			-o out/doc/api \
-			-c ./CHANGELOG.md \
-			-v $(VERSION) \
-			--index doc/api/index.md \
-			--type-map doc/type-map.json \
-		) \
-	fi
-endif
-
-out/doc/llms.txt: $(apidoc_sources) tools/doc/node_modules | out/doc
-	@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 llms-txt \
-			-i doc/api/*.md \
-			--ignore $(skip_apidoc_files) \
-			-o $(@D) \
-			-c ./CHANGELOG.md \
+			--log-level debug \
+			--config-file tools/doc/web.doc-kit.config.mjs \
 			-v $(VERSION) \
-			--type-map doc/type-map.json \
+			$(if $(JOBS),-p $(JOBS)) \
 		) \
 	fi
 
@@ -923,12 +890,9 @@ 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 \
+			--config-file tools/doc/api-links.doc-kit.config.mjs \
 			-o $(@D) \
-			-c ./CHANGELOG.md \
 			-v $(VERSION) \
-			--type-map doc/type-map.json \
 		) \
 	fi
 

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$
@@ -225,7 +225,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.
@@ -344,11 +344,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.

test/doctool/test-make-doc.mjs

@@ -0,0 +1,17 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const fromRoot = (path) =>
+  pathToFileURL(join(import.meta.dirname, '..', '..', path)).href;
+
+export default {
+  extends: '@node-core/doc-kit/config',
+
+  target: ['api-links'],
+
+  global: {
+    input: ['lib/*.js'],
+
+    changelog: fromRoot('CHANGELOG.md'),
+  },
+};