Process admonitions with remark

frontend/package.json

@@ -23,6 +23,7 @@
     "@vitejs/plugin-react": "^4.3.1",
     "autoprefixer": "^10.4.20",
     "clsx": "^2.1.1",
+    "es-toolkit": "^1.17.0",
     "eslint": "^9.9.1",
     "eslint-plugin-react-hooks": "^5.1.0-rc.0",
     "eslint-plugin-react-refresh": "^0.4.11",
@@ -44,8 +45,10 @@
     "rehype-sanitize": "^6.0.0",
     "rehype-slug": "^6.0.0",
     "rehype-stringify": "^10.0.0",
+    "remark-directive": "^3.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.0",
+    "remark-github-admonitions-to-directives": "^2.0.0",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.0",
     "suspend-react": "^0.1.3",

frontend/src/components/Markdown/Admonition.tsx

@@ -0,0 +1,66 @@
+import clsx from "clsx";
+import { ReactNode } from "react";
+
+export enum AdmonitionType {
+  NOTE = "note",
+  CAUTION = "caution",
+  WARNING = "warning",
+  TIP = "tip",
+  INFO = "info",
+  IMPORTANT = "important",
+}
+
+function getAdmonitionClassName(type: AdmonitionType) {
+  switch (type) {
+    case AdmonitionType.NOTE:
+      return "bg-sky-100 text-sky-800 dark:bg-sky-950 dark:text-sky-100";
+    case AdmonitionType.CAUTION:
+      return "bg-red-100 text-red-800 dark:bg-red-950 dark:text-red-100";
+    case AdmonitionType.WARNING:
+      return "bg-yellow-100 text-yellow-800 dark:bg-yellow-950 dark:text-yellow-100";
+    case AdmonitionType.TIP:
+      return "bg-green-100 text-green-800 dark:bg-green-950 dark:text-green-100";
+    case AdmonitionType.IMPORTANT:
+    case AdmonitionType.INFO:
+      return "bg-purple-100 text-purple-800 dark:bg-purple-950 dark:text-purple-100";
+  }
+}
+
+function getAdmonitionTitle(type: AdmonitionType) {
+  switch (type) {
+    case AdmonitionType.NOTE:
+      return "Note";
+    case AdmonitionType.CAUTION:
+      return "Caution";
+    case AdmonitionType.WARNING:
+      return "Warning";
+    case AdmonitionType.TIP:
+      return "Tip";
+    case AdmonitionType.IMPORTANT:
+    case AdmonitionType.INFO:
+      return "Important";
+  }
+}
+
+interface AdmonitionProps {
+  type?: AdmonitionType;
+  children: ReactNode;
+}
+
+export function Admonition({ type, children }: AdmonitionProps) {
+  const className = type ? getAdmonitionClassName(type) : null;
+
+  return (
+    <div
+      className={clsx(
+        "mt-5 px-3 py-2 first:mt-0 [&>details]:mt-2.5 [&>h6]:mt-4 [&>p]:mt-2.5 [li>&:first-child]:mt-0",
+        className,
+      )}
+    >
+      {type && (
+        <strong className="font-semibold">{getAdmonitionTitle(type)}</strong>
+      )}
+      {children}
+    </div>
+  );
+}

frontend/src/components/Markdown/Blockquote.tsx

@@ -0,0 +1,11 @@
+import { BlockquoteHTMLAttributes } from "react";
+
+export function MarkdownBlockquote({
+  children,
+}: BlockquoteHTMLAttributes<HTMLQuoteElement>) {
+  return (
+    <blockquote className="mt-5 flex flex-col border-l-2 border-gray-500 pl-5">
+      {children}
+    </blockquote>
+  );
+}

frontend/src/components/Markdown/index.tsx

@@ -7,8 +7,10 @@ import remarkRehype from "remark-rehype";
 import rehypeSlug from "rehype-slug";
 import remarkGfm from "remark-gfm";
 import rehypeReact, { Options } from "rehype-react";
-import rehypeSanitize from "rehype-sanitize";
+import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
 import rehypeRaw from "rehype-raw";
+import remarkDirective from "remark-directive";
+import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives";
 import { unified } from "unified";
 import { MarkdownH1 } from "./H1";
 import { MarkdownP } from "./P";
@@ -25,6 +27,12 @@ import { MarkdownTh } from "./Th";
 import { MarkdownImg } from "./Img";
 import { MarkdownOl } from "./Ol";
 import { MarkdownHr } from "./Hr";
+import { MarkdownBlockquote } from "./Blockquote";
+import { visit, CONTINUE } from "unist-util-visit";
+import { merge } from "es-toolkit";
+import { Admonition, AdmonitionType } from "./Admonition";
+import { Plugin } from "unified";
+import { Directives } from "mdast-util-directive";
 
 const production: Options = {
   development: false,
@@ -47,9 +55,46 @@ const production: Options = {
     img: MarkdownImg,
     ol: MarkdownOl,
     hr: MarkdownHr,
+    blockquote: MarkdownBlockquote,
+    admonition: Admonition,
   },
 };
 
+const makeDirectives: Plugin = () => {
+  const admonitionTypes: string[] = Object.values(AdmonitionType);
+
+  return (tree) => {
+    visit(
+      tree,
+      ["textDirective", "leafDirective", "containerDirective"],
+      (node, index, parent) => {
+        const directiveNode = node as Directives;
+
+        if (!admonitionTypes.includes(directiveNode.name)) return CONTINUE;
+
+        // parent.children.splice(index, 1, {
+        //   type: "element",
+        //   data: {
+        //     hName: "admonition",
+        //     hProperties: {
+        //       type: directiveNode.name,
+        //     },
+        //   },
+        //   children: node.children,
+        // });
+
+        directiveNode.data ??= {};
+
+        directiveNode.data.hName = "admonition";
+
+        directiveNode.data.hProperties = {
+          type: directiveNode.name,
+        };
+      },
+    );
+  };
+};
+
 interface MarkdownProps {
   text: string;
 }
@@ -61,10 +106,24 @@ export function Markdown({ text }: MarkdownProps) {
         .use(remarkParse)
         .use(remarkFrontmatter)
         .use(remarkGfm)
-        .use(remarkRehype, { allowDangerousHtml: true }) // This is okay to use dangerous html because we are sanitizing later on in the pipeline
-        .use(rehypeRaw)
-        .use(rehypeSanitize)
+        .use(remarkGithubAdmonitionsToDirectives)
+        .use(remarkDirective)
+        .use(makeDirectives)
+        .use(remarkRehype, {
+          // This is okay to use dangerous html because we are sanitizing later on in the pipeline
+          allowDangerousHtml: true,
+        })
         .use(rehypeSlug)
+        .use(rehypeRaw, {
+          passThrough: ["admonition"],
+        })
+        .use(
+          rehypeSanitize,
+          merge(defaultSchema, {
+            tagNames: ["admonition"],
+            attributes: { admonition: ["type"] },
+          }),
+        )
         .use(rehypeReact, production)
         .processSync(text),
     [text],