feat: support tex math dollar syntax in project documentation

functions/chips/[shuttle]/[project]/index.ts

@@ -76,6 +76,12 @@ export const onRequestGet: PagesFunction<Env> = async (context) => {
           `<meta property="og:image:width" content="1200" />`,
           `<meta property="og:image:height" content="630" />`,
           '<meta name="twitter:card" content="summary_large_image"/>',
+
+          // if this stylesheet is missing, then the equation text is duplicated on page
+          // see https://katex.org/docs/browser
+          `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" 
+          integrity="sha384-Pu5+C18nP5dwykLJOhd2U4Xen7rjScHN/qusop27hdd2drI+lL5KvX7YntvT8yew" crossorigin="anonymous">`,
+          `<link href="/css/katex.css" rel="stylesheet">`,
         ].join('\n'),
       )
       .replaceAll('__ttreplace_shuttle_id__', shuttle)

functions/components/ProjectPage.tsx

@@ -3,6 +3,7 @@
 
 import MarkdownIt from 'markdown-it';
 import React from 'react';
+import katex from 'katex';
 import { IProjectFeedbackList, summarizeFeedback } from '../model/feedback.js';
 import { markdownHeadingLimiter, markdownImagePathTransformer } from '../model/project.js';
 import { getShuttlePdk, scanchainShuttles, type IShuttleIndexProject } from '../model/shuttle.js';
@@ -27,7 +28,16 @@ export function ProjectPage({
   feedback,
   shuttleMapSvg,
 }: IProjectPropProps) {
-  const md = MarkdownIt();
+  const md = MarkdownIt().use(require('markdown-it-texmath'), {
+    engine: katex,
+    // see https://katex.org/docs/options for all options
+    katexOptions: {
+      throwOnError: true,
+      strict: true, // be faithful to LaTeX math
+      trust: false, // prevent commands which cause adverse behaviour
+      maxSize: 80,
+    },
+  });
 
   // Add base URL to image paths
   md.renderer.rules['image'] = markdownImagePathTransformer(shuttle, project.macro);

package.json

@@ -20,7 +20,9 @@
   },
   "dependencies": {
     "@cloudflare/pages-plugin-vercel-og": "^0.1.2",
+    "katex": "^0.16.27",
     "markdown-it": "^14.1.0",
+    "markdown-it-texmath": "^1.0.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },

static/css/katex.css

@@ -0,0 +1,11 @@
+/* set font-size to match the rest of the content (https://katex.org/docs/font) */
+.katex {
+  font-size: 1em;
+}
+
+/* hide equation numbering - this isn't supported in the datasheet, so to avoid confusion i'll just hide it
+   there is no option to toggle it, see https://github.com/KaTeX/KaTeX/discussions/3180
+*/
+.eqn-num {
+  display: none !important;
+}