web: Fix inline documentation rendering (#13379)

web: Fix issues surrounding markdown rendering.

- Fix issue where Mermaid diagrams do not render.
- Fix link colors in dark mode.
- Fix anchored links triggering router.
- Fix issue where links occasionally link to missing page.

web/scripts/esbuild/remark/remark-admonition.mjs

@@ -0,0 +1,46 @@
+/**
+ * @import {Plugin} from 'unified'
+ * @import {Directives} from 'mdast-util-directive'
+ * @import {} from 'mdast-util-to-hast'
+ * @import {Root} from 'mdast'
+ * @import {VFile} from 'vfile'
+ */
+import { h } from "hastscript";
+import { visit } from "unist-util-visit";
+
+const ADMONITION_TYPES = new Set(["info", "warning", "danger", "note"]);
+
+/**
+ * Remark plugin to process links
+ * @type {Plugin<[unknown], Root, VFile>}
+ */
+export function remarkAdmonition() {
+    return function transformer(tree) {
+        /**
+         * @param {Directives} node
+         */
+        const visitor = (node) => {
+            if (
+                node.type === "containerDirective" ||
+                node.type === "leafDirective" ||
+                node.type === "textDirective"
+            ) {
+                if (!ADMONITION_TYPES.has(node.name)) return;
+
+                const data = node.data || (node.data = {});
+
+                const tagName = node.type === "textDirective" ? "span" : "ak-alert";
+
+                data.hName = tagName;
+
+                const element = h(tagName, node.attributes || {});
+
+                data.hProperties = element.properties || {};
+                data.hProperties.level = `pf-m-${node.name}`;
+            }
+        };
+
+        // @ts-ignore - visit cannot infer the type of the visitor.
+        visit(tree, visitor);
+    };
+}

web/scripts/esbuild/remark/remark-headings.mjs

@@ -0,0 +1,33 @@
+/**
+ * @import {Plugin} from 'unified'
+ * @import {Root, Heading} from 'mdast'
+ * @import {VFile} from 'vfile'
+ */
+import { kebabCase } from "change-case";
+import { toString } from "mdast-util-to-string";
+import { visit } from "unist-util-visit";
+
+/**
+ * Remark plugin to process links
+ * @type {Plugin<[unknown], Root, VFile>}
+ */
+export const remarkHeadings = () => {
+    return function transformer(tree) {
+        /**
+         * @param {Heading} node
+         */
+        const visitor = (node) => {
+            const textContent = toString(node);
+            const id = kebabCase(textContent);
+
+            node.data = node.data || {};
+            node.data.hProperties = {
+                ...node.data.hProperties,
+                id,
+            };
+        };
+
+        // @ts-ignore - visit cannot infer the type of the visitor.
+        visit(tree, "heading", visitor);
+    };
+};

web/scripts/esbuild/remark/remark-links.mjs

@@ -0,0 +1,59 @@
+/**
+ * @import {Plugin} from 'unified'
+ * @import {} from 'mdast-util-directive'
+ * @import {} from 'mdast-util-to-hast'
+ * @import {Root, Link} from 'mdast'
+ * @import {VFile} from 'vfile'
+ */
+import * as path from "node:path";
+import { visit } from "unist-util-visit";
+
+const DOCS_DOMAIN = "https://goauthentik.io";
+
+/**
+ * Remark plugin to process links
+ * @type {Plugin<[unknown], Root, VFile>}
+ */
+export const remarkLinks = () => {
+    return function transformer(tree, file) {
+        const docsRoot = path.resolve(file.cwd, "..", "website");
+
+        /**
+         * @param {Link} node
+         */
+        const visitor = (node) => {
+            node.data = node.data || {};
+
+            if (node.url.startsWith("#")) {
+                node.data.hProperties = {
+                    className: "markdown-heading",
+                };
+
+                return;
+            }
+
+            node.data.hProperties = {
+                ...node.data.hProperties,
+                rel: "noopener noreferrer",
+                target: "_blank",
+            };
+
+            if (node.url.startsWith(".") && file.dirname) {
+                const nextPathname = path.resolve(
+                    "/",
+                    path.relative(docsRoot, file.dirname),
+                    node.url,
+                );
+                const nextURL = new URL(nextPathname, DOCS_DOMAIN);
+
+                // Remove trailing .md and .mdx, and trailing "index".
+                nextURL.pathname = nextURL.pathname.replace(/(index)?\.mdx?$/, "");
+
+                node.data.hProperties.href = nextURL.toString();
+            }
+        };
+
+        // @ts-ignore - visit cannot infer the type of the visitor.
+        visit(tree, "link", visitor);
+    };
+};

web/scripts/esbuild/remark/remark-lists.mjs

@@ -0,0 +1,29 @@
+/**
+ * @import {Plugin} from 'unified'
+ * @import {Root, List} from 'mdast'
+ * @import {VFile} from 'vfile'
+ */
+import { visit } from "unist-util-visit";
+
+/**
+ * Remark plugin to process links
+ * @type {Plugin<[unknown], Root, VFile>}
+ */
+export const remarkLists = () => {
+    return function transformer(tree) {
+        /**
+         * @param {List} node
+         */
+        const visitor = (node) => {
+            node.data = node.data || {};
+
+            node.data.hProperties = {
+                ...node.data.hProperties,
+                className: "pf-c-list",
+            };
+        };
+
+        // @ts-ignore - visit cannot infer the type of the visitor.
+        visit(tree, "list", visitor);
+    };
+};