Upgrade to highlight.js v11

I was on the fence about this one as v11 removed auto-merging of HTML
into formatted blocks. This feature supports AsciiDoc callouts.
See: https://docs.asciidoctor.org/asciidoc/latest/verbatim/callouts/ if
you need a reminder as to what these are.

After more carefully reading over highlightjs/highlight.js#2889, I
realized maybe it wouldn't be very difficult to simply re-introduce the
feature. The issue even includes a complete JavaScript code example to
do so.

I did my naive best to transcribe the sample JavaScript to TypeScript
(which even caught a couple of minor issues).

It took me some time to figure out a way to expose the TypeScript
function to our layout page. Parcel.js used to provide a --global
option to support this use case, but that feature was removed.

In the end I just assigned the function to the browser window to make it
available.

There is a new console warning in highlight.js v11 that is generated
when formatted code contains unescaped HTML. I turned this off because
the adoc callouts add... you guessed it... unescaped HTML. We also have
good HTML sanitization, so I think we are good here.

js/hljs-merge-plugin.ts

@@ -0,0 +1,198 @@
+// highlight.js 11 removed the 'HTML auto-merging' internal plugin
+// however this is required for AsciiDoc to insert callouts
+// fortunately the issue description shows how to re-enable it, by registering the plugin
+// See https://github.com/highlightjs/highlight.js/issues/2889
+
+// Naively transcribed to TypeScript
+var originalStream: Event[];
+
+/**
+ * @param value
+ * @returns escaped html
+ */
+function escapeHTML(value: string) {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#x27;");
+}
+
+const mergeHTMLPlugin = {
+  // preserve the original HTML token stream
+  "before:highlightElement": ({ el }: { el: HTMLElement }) => {
+    originalStream = nodeStream(el);
+  },
+  // merge it afterwards with the highlighted token stream
+  "after:highlightElement": ({
+    el,
+    result,
+    text
+  }: {
+    el: HTMLElement;
+    result: Result;
+    text: string;
+  }) => {
+    if (!originalStream.length) return;
+
+    const resultNode = document.createElement("div");
+    resultNode.innerHTML = result.value;
+    result.value = mergeStreams(originalStream, nodeStream(resultNode), text);
+    el.innerHTML = result.value;
+  }
+};
+
+/* Stream merging support functions */
+
+type Result = {
+  value: string;
+};
+
+type Event = {
+  event: "start" | "stop";
+  offset: number;
+  node: Node;
+};
+
+/**
+ * @param {Node} node
+ */
+function tag(node: Node) {
+  return node.nodeName.toLowerCase();
+}
+
+/**
+ * @param node
+ * returns events
+ */
+function nodeStream(node: Node) {
+  const result: Event[] = [];
+  (function _nodeStream(node, offset) {
+    for (let child = node.firstChild; child; child = child.nextSibling) {
+      if (child.nodeType === Node.TEXT_NODE) {
+        if (child.nodeValue) {
+          offset += child.nodeValue.length;
+        }
+      } else if (child.nodeType === Node.ELEMENT_NODE) {
+        result.push({
+          event: "start",
+          offset: offset,
+          node: child
+        });
+        offset = _nodeStream(child, offset);
+        // Prevent void elements from having an end tag that would actually
+        // double them in the output. There are more void elements in HTML
+        // but we list only those realistically expected in code display.
+        if (!tag(child).match(/br|hr|img|input/)) {
+          result.push({
+            event: "stop",
+            offset: offset,
+            node: child
+          });
+        }
+      }
+    }
+    return offset;
+  })(node, 0);
+  return result;
+}
+
+/**
+ * @param original - the original stream
+ * @param highlighted - stream of the highlighted source
+ * @param value - the original source itself
+ */
+function mergeStreams(original: any, highlighted: any, value: string) {
+  let processed = 0;
+  let result = "";
+  const nodeStack = [];
+
+  function selectStream() {
+    if (!original.length || !highlighted.length) {
+      return original.length ? original : highlighted;
+    }
+    if (original[0].offset !== highlighted[0].offset) {
+      return original[0].offset < highlighted[0].offset
+        ? original
+        : highlighted;
+    }
+
+    /*
+        To avoid starting the stream just before it should stop the order is
+        ensured that original always starts first and closes last:
+        if (event1 == 'start' && event2 == 'start')
+          return original;
+        if (event1 == 'start' && event2 == 'stop')
+          return highlighted;
+        if (event1 == 'stop' && event2 == 'start')
+          return original;
+        if (event1 == 'stop' && event2 == 'stop')
+          return highlighted;
+         ... which is collapsed to:
+      */
+    return highlighted[0].event === "start" ? original : highlighted;
+  }
+
+  /**
+   * @param node
+   */
+  function open(node: HTMLElement) {
+    /** @param attr */
+    function attributeString(attr: Attr) {
+      return " " + attr.nodeName + '="' + escapeHTML(attr.value) + '"';
+    }
+    // @ts-ignore
+    result +=
+      "<" +
+      tag(node) +
+      [].map.call(node.attributes, attributeString).join("") +
+      ">";
+  }
+
+  /**
+   * @param node
+   */
+  function close(node: HTMLElement) {
+    result += "</" + tag(node) + ">";
+  }
+
+  /**
+   * @param event
+   */
+  function render(event: Event) {
+    (event.event === "start" ? open : close)(event.node as HTMLElement);
+  }
+
+  while (original.length || highlighted.length) {
+    let stream = selectStream();
+    result += escapeHTML(value.substring(processed, stream[0].offset));
+    processed = stream[0].offset;
+    if (stream === original) {
+      /* On any opening or closing tag of the original markup we first close
+           the entire highlighted node stack, then render the original tag along
+           with all the following original tags at the same offset and then
+           reopen all the tags on the highlighted stack. */
+      nodeStack.reverse().forEach(close);
+      do {
+        render(stream.splice(0, 1)[0]);
+        stream = selectStream();
+      } while (
+        stream === original &&
+        stream.length &&
+        stream[0].offset === processed
+      );
+      nodeStack.reverse().forEach(open);
+    } else {
+      if (stream[0].event === "start") {
+        nodeStack.push(stream[0].node);
+      } else {
+        nodeStack.pop();
+      }
+      render(stream.splice(0, 1)[0]);
+    }
+  }
+  return result + escapeHTML(value.substring(processed));
+}
+
+export { mergeHTMLPlugin };

js/index.tsx

@@ -17,6 +17,7 @@ import {
 } from "./cljdoc";
 import { initRecentDocLinks } from "./recent-doc-links";
 import { mountSingleDocsetSearch } from "./single-docset-search";
+import { mergeHTMLPlugin } from "./hljs-merge-plugin";
 
 export type SidebarScrollPos = { page: string; scrollTop: number };
 
@@ -82,3 +83,6 @@ mountSingleDocsetSearch();
 
 // Save the sidebar scroll position when navigating away from the site so we can restore it later.
 window.onbeforeunload = saveSidebarScrollPos;
+
+// make the hljs plugin available to our layout page
+window.mergeHTMLPlugin = mergeHTMLPlugin;

js/window.d.ts

@@ -0,0 +1,7 @@
+export {};
+
+declare global {
+  interface Window {
+    mergeHTMLPlugin: any; // allows us to expose our hljs plugin
+  }
+}

resources/asset-deps.edn

@@ -78,8 +78,7 @@
                  "jax/output/PreviewHTML/jax.js"]}}
  :highlightjs
  {:npm-name "highlight.js"
-  :note "Highlight.js v11 will require some plugin to support our AsciiDoc inline code callouts.\nSee: https://github.com/highlightjs/highlight.js/issues/2889"
-  :version "10.7.2"
+  :version "11.7.0"
   :js {:root "https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@{{:version}}/build/"
        :assets ["highlight.min.js"
                 "languages/clojure.min.js"

src/cljdoc/render/layout.clj

@@ -13,7 +13,9 @@
 (defn highlight-js-customization []
   [:script
    (hiccup/raw
-    "hljs.registerLanguage('cljs', function (hljs) { return hljs.getLanguage('clj') });
+    "hljs.configure({ignoreUnescapedHTML: true});
+     hljs.addPlugin(mergeHTMLPlugin);
+     hljs.registerLanguage('cljs', function (hljs) { return hljs.getLanguage('clj') });
      hljs.highlightAll();")])
 
 (defn highlight-js []