feat(syntax-highlight): do client side, support more languages (#11654)

Co-authored-by: Florian Dieminger <[email protected]>

Author: LeoMcA

Diff for: build/blog.ts

@@ -28,7 +28,7 @@ import {
   postProcessSmallerHeadingIDs,
 } from "./utils.js";
 import { slugToFolder } from "../libs/slug-utils/index.js";
-import { syntaxHighlight } from "./syntax-highlight.js";
+import { wrapCodeExamples } from "./code-headers.js";
 import { wrapTables } from "./wrap-tables.js";
 import { Doc } from "../libs/types/document.js";
 import { extractSections } from "./extract-sections.js";
@@ -391,7 +391,7 @@ export async function buildPost(
     doc.hasMathML = true;
   }
   $("div.hidden").remove();
-  syntaxHighlight($, doc);
+  wrapCodeExamples($);
   injectNoTranslate($);
   injectLoadingLazyAttributes($);
   postProcessExternalLinks($);

Diff for: build/code-headers.ts

@@ -0,0 +1,45 @@
+import * as cheerio from "cheerio";
+
+// Over the years we have accumulated some weird <pre> tags whose
+// brush is more or less "junk".
+// TODO: Perhaps, if you have a doc with <pre> tags that matches
+// this, it should become a flaw.
+const IGNORE = new Set(["none", "text", "plain", "unix"]);
+
+/**
+ * Mutate the `$` instance by adding headers to <pre> tags containing code blocks.
+ *
+ */
+export function wrapCodeExamples($: cheerio.CheerioAPI) {
+  // Our content will be like this: `<pre class="brush:js">` or
+  // `<pre class="brush: js">` so we're technically not looking for an exact
+  // match. The wildcard would technically match `<pre class="brushetta">`
+  // too. But within the loop, we do a more careful regex on the class name
+  // and only proceed if it's something sensible.
+  $("pre[class*=brush]").each((_, element) => {
+    // The language is whatever string comes after the `brush(:)`
+    // portion of the class name.
+    const $pre = $(element);
+
+    const className = $pre.attr("class").toLowerCase();
+    const match = className.match(/brush:?\s*([\w_-]+)/);
+    if (!match) {
+      return;
+    }
+    const name = match[1].replace("-nolint", "");
+    if (IGNORE.has(name)) {
+      // Seems to exist a couple of these in our docs. Just bail.
+      return;
+    }
+    const code = $pre.text();
+    $pre.wrapAll(`<div class='code-example'></div>`);
+    if (!$pre.hasClass("hidden")) {
+      $(
+        `<div class='example-header'><span class="language-name">${name}</span></div>`
+      ).insertBefore($pre);
+    }
+    const $code = $("<code>").text(code);
+
+    $pre.empty().append($code);
+  });
+}

Diff for: build/curriculum.ts

@@ -9,7 +9,7 @@ import { DocParent } from "../libs/types/document.js";
 import { CURRICULUM_TITLE, DEFAULT_LOCALE } from "../libs/constants/index.js";
 import * as kumascript from "../kumascript/index.js";
 import LANGUAGES_RAW from "../libs/languages/index.js";
-import { syntaxHighlight } from "./syntax-highlight.js";
+import { wrapCodeExamples } from "./code-headers.js";
 import {
   escapeRegExp,
   injectLoadingLazyAttributes,
@@ -321,7 +321,7 @@ export async function buildCurriculumPage(
     doc.hasMathML = true;
   }
   $("div.hidden").remove();
-  syntaxHighlight($, doc);
+  wrapCodeExamples($);
   injectNoTranslate($);
   injectLoadingLazyAttributes($);
   postProcessCurriculumLinks($, (p: string | undefined) => {

Diff for: build/index.ts

@@ -28,7 +28,7 @@ import {
 } from "./flaws/index.js";
 import { checkImageReferences, checkImageWidths } from "./check-images.js";
 import { getPageTitle } from "./page-title.js";
-import { syntaxHighlight } from "./syntax-highlight.js";
+import { wrapCodeExamples } from "./code-headers.js";
 import { formatNotecards } from "./format-notecards.js";
 import buildOptions from "./build-options.js";
 import LANGUAGES_RAW from "../libs/languages/index.js";
@@ -456,8 +456,8 @@ export async function buildDocument(
     plainHTML = $.html();
   }
 
-  // Apply syntax highlighting all <pre> tags.
-  syntaxHighlight($, doc);
+  // Add headers to all <pre> tags with code.
+  wrapCodeExamples($);
 
   // Post process HTML so that the right elements gets tagged so they
   // *don't* get translated by tools like Google Translate.

Diff for: build/syntax-highlight.ts

@@ -14,10 +14,7 @@ import {
   BlogPostLimitedMetadata,
   AuthorMetadata,
 } from "../../../libs/types/blog";
-import {
-  useCopyExamplesToClipboardAndAIExplain,
-  useRunSample,
-} from "../document/hooks";
+import { useDecorateCodeExamples, useRunSample } from "../document/hooks";
 import { DEFAULT_LOCALE } from "../../../libs/constants";
 import { SignUpSection as NewsletterSignUp } from "../newsletter";
 import { TOC } from "../document/organisms/toc";
@@ -190,7 +187,7 @@ export function BlogPost(props: HydrationData) {
   );
   const { doc, blogMeta } = data || props || {};
   useRunSample(doc);
-  useCopyExamplesToClipboardAndAIExplain(doc);
+  useDecorateCodeExamples(doc);
   return (
     <>
       {doc && blogMeta && (