tools: support rewriting links in code blocks

Within the API documentation for modules, there is a section of
pseudo-code which contains links to another file. This pseudo-code is
inside of a pre-formatted element (`<pre>`), but that prevents the
build process from rewriting those links from the Markdown source to
their corresponding HTML output.

This addresses that by adding a new language, "pre", whose output
remains unformatted but allows code fences to be annotated with
metadata - code fences must have a language before the metadata. When
the right metadata ("html") is present, it indicates that the code
block should be processed so that anchor tags are rewritten just like
other references.

The actual change to the documentation will happen in a later commit.

Author: crawford

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];