doc: fix links to ECMAScript module resolution

doc/api/modules.md

@@ -235,7 +235,7 @@ the `require.resolve()` function.
 Putting together all of the above, here is the high-level algorithm
 in pseudocode of what `require()` does:
 
-<pre>
+```pre html
 require(X) from module at path Y
 1. If X is a core module,
    a. return the core module
@@ -256,7 +256,7 @@ MAYBE_DETECT_AND_LOAD(X)
 1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.
 2. Else, if `--experimental-require-module` and `--experimental-detect-module` are
   enabled, and the source code of X can be parsed as ECMAScript module using
-  <a href="esm.md#resolver-algorithm-specification">DETECT_MODULE_SYNTAX defined in
+  <a href="esm.md#resolution-algorithm-specification">DETECT_MODULE_SYNTAX defined in
   the ESM resolver</a>,
   a. Load X as an ECMAScript module. STOP.
 3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.
@@ -318,7 +318,7 @@ LOAD_PACKAGE_IMPORTS(X, DIR)
 2. If no scope was found, return.
 3. If the SCOPE/package.json "imports" is null or undefined, return.
 4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),
-  ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+  ["node", "require"]) <a href="esm.md#resolution-algorithm-specification">defined in the ESM resolver</a>.
 5. RESOLVE_ESM_MATCH(MATCH).
 
 LOAD_PACKAGE_EXPORTS(X, DIR)
@@ -329,7 +329,7 @@ LOAD_PACKAGE_EXPORTS(X, DIR)
 3. Parse DIR/NAME/package.json, and look for "exports" field.
 4. If "exports" is null or undefined, return.
 5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,
-   `package.json` "exports", ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+   `package.json` "exports", ["node", "require"]) <a href="esm.md#resolution-algorithm-specification">defined in the ESM resolver</a>.
 6. RESOLVE_ESM_MATCH(MATCH)
 
 LOAD_PACKAGE_SELF(X, DIR)
@@ -339,15 +339,15 @@ LOAD_PACKAGE_SELF(X, DIR)
 4. If the SCOPE/package.json "name" is not the first segment of X, return.
 5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),
    "." + X.slice("name".length), `package.json` "exports", ["node", "require"])
-   <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+   <a href="esm.md#resolution-algorithm-specification">defined in the ESM resolver</a>.
 6. RESOLVE_ESM_MATCH(MATCH)
 
 RESOLVE_ESM_MATCH(MATCH)
 1. let RESOLVED_PATH = fileURLToPath(MATCH)
 2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension
    format. STOP
 3. THROW "not found"
-</pre>
+```
 
 ## Caching
 

doc/contributing/api-documentation.md

@@ -4,9 +4,8 @@ The Node.js API documentation is generated by an in-house tooling that resides
 within the [tools/doc](https://github.com/nodejs/node/tree/main/tools/doc)
 directory.
 
-The build process (using `make doc`) uses this tooling to parse the markdown
-files in [doc/api](https://github.com/nodejs/node/tree/main/doc/api) and
-generate the following:
+The build process (using `make doc` or `make doc-only`) uses this tooling to
+parse the markdown files in [doc/api][] and generate the following:
 
 1. Human-readable HTML in `out/doc/api/*.html`
 2. A JSON representation in `out/doc/api/*.json`
@@ -302,3 +301,5 @@ mutate the data and appends it to the final JSON object.
 
 For a more in-depth information we recommend to refer to the `json.mjs` file as
 it contains a lot of comments.
+
+[doc/api]: https://github.com/nodejs/node/tree/main/doc/api

tools/doc/html.mjs

@@ -205,6 +205,7 @@ function linkJsTypeDocs(text) {
 }
 
 const isJSFlavorSnippet = (node) => node.lang === 'cjs' || node.lang === 'mjs';
+const isPreSnippet = (node) => node.lang === 'pre';
 
 // Preprocess headers, stability blockquotes, and YAML blocks.
 export function preprocessElements({ filename }) {
@@ -265,6 +266,8 @@ export function preprocessElements({ filename }) {
             // Isolated JS snippet, no need to add the checkbox.
             node.value = `<pre>${highlighted} ${copyButton}</pre>`;
           }
+        } else if (isPreSnippet(node)) {
+          node.value = `<pre>${node.value}</pre>`;
         } else {
           node.value = `<pre>${highlighted} ${copyButton}</pre>`;
         }

tools/doc/markdown.mjs

@@ -1,6 +1,7 @@
 import { visit } from 'unist-util-visit';
 
 export const referenceToLocalMdFile = /^(?![+a-z]+:)([^#?]+)\.md(#.+)?$/i;
+export const referenceToLocalMdFileInPre = /<a href="([^#"]+)\.md(#[^"]+)?">/g;
 
 export function replaceLinks({ filename, linksMapper }) {
   return (tree) => {
@@ -14,6 +15,14 @@ export function replaceLinks({ filename, linksMapper }) {
         );
       }
     });
+    visit(tree, 'code', (node) => {
+      if (node.meta === 'html') {
+        node.value = node.value.replace(
+          referenceToLocalMdFileInPre,
+          (_, path, fragment) => `<a href="${path}.html${fragment || ''}">`,
+        );
+      }
+    });
     visit(tree, 'definition', (node) => {
       const htmlUrl = fileHtmlUrls && fileHtmlUrls[node.identifier];
 

tools/lint-md/lint-md.mjs

@@ -23409,6 +23409,7 @@ const plugins = [
         "markdown",
         "mjs",
         "powershell",
+        "pre",
         "r",
         "text",
         "ts",