From 70046d0c74f59ac3f2798d9fb1b6553f52e99a78 Mon Sep 17 00:00:00 2001
From: Brandon Oxendine <brandon.oxendine@gmail.com>
Date: Mon, 7 Sep 2026 17:19:11 +0200
Subject: [PATCH] Render GitHub style alerts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A blockquote starting with `[!NOTE]` or one of its siblings showed up
as a plain quote, while GitHub and the web explorer render it as a
titled callout.

Co-authored-by: Rūdolfs Ošiņš <rudolfs@osins.org>
---
 public/colors.css                        |  4 ++
 src/components/Markdown.svelte           | 58 ++++++++++++++++++++++++
 src/lib/markdown.ts                      | 58 +++++++++++++++++++++++-
 tests/e2e/repo/markdownRendering.spec.ts | 29 ++++++++++++
 4 files changed, 148 insertions(+), 1 deletion(-)
 create mode 100644 tests/e2e/repo/markdownRendering.spec.ts

diff --git a/public/colors.css b/public/colors.css
index 5708e3b72..18a9ea6c8 100644
--- a/public/colors.css
+++ b/public/colors.css
@@ -43,6 +43,8 @@
   --color-feedback-error-border: var(--color-semantic-red-600);
   --color-feedback-error-bg: var(--color-semantic-red-100);
   --color-feedback-error-bg-selected: var(--color-semantic-red-200);
+  --color-feedback-info-text: var(--color-semantic-blue-800);
+  --color-feedback-important-text: var(--color-accent-purple-800);
 
   --color-diff-addition: var(--color-semantic-green-500);
   --color-diff-deletion: var(--color-semantic-red-500);
@@ -121,6 +123,8 @@
   --color-feedback-error-border: var(--color-semantic-red-700);
   --color-feedback-error-bg: var(--color-semantic-red-900);
   --color-feedback-error-bg-selected: var(--color-semantic-red-800);
+  --color-feedback-info-text: var(--color-semantic-blue-400);
+  --color-feedback-important-text: var(--color-accent-purple-400);
 
   --color-diff-addition: var(--color-semantic-green-400);
   --color-diff-deletion: var(--color-semantic-red-400);
diff --git a/src/components/Markdown.svelte b/src/components/Markdown.svelte
index a51e2240d..687719237 100644
--- a/src/components/Markdown.svelte
+++ b/src/components/Markdown.svelte
@@ -1,3 +1,13 @@
+<script lang="ts" module>
+  const alertIcons = {
+    note: "guide",
+    tip: "lightbulb",
+    important: "comment",
+    warning: "warning",
+    caution: "stop",
+  } as const;
+</script>
+
 <script lang="ts">
   import { mount, tick, unmount } from "svelte";
 
@@ -6,6 +16,7 @@
   import { parseFrontmatter } from "@app/lib/frontmatter";
   import { invoke } from "@app/lib/invoke";
   import {
+    alertVariants,
     isTaskCheckbox,
     maximumReferences,
     renderMarkdown,
@@ -332,6 +343,21 @@
         }
       }
 
+      for (const title of container.querySelectorAll("p.alert-title")) {
+        const variant = alertVariants.find(name =>
+          title.parentElement?.classList.contains(`alert-${name}`),
+        );
+        if (!variant) continue;
+
+        icons.push(
+          mount(Icon, {
+            target: title,
+            anchor: title.firstChild ?? undefined,
+            props: { name: alertIcons[variant] },
+          }),
+        );
+      }
+
       enhanceCodeBlocks(container);
 
       if (!scrolledToHash && window.location.hash) {
@@ -657,6 +683,38 @@
   .markdown :global(dl dd) {
     margin: 0 0 0 2rem;
   }
+
+  .markdown :global(.alert) {
+    border-left: 0.3rem solid var(--alert-color);
+    padding: 0 0 0 1rem;
+    margin: 1rem 0;
+  }
+  .markdown :global(.alert > .alert-title) {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    color: var(--alert-color);
+    font: var(--txt-body-m-semibold);
+    margin-bottom: 0.375rem;
+  }
+  .markdown :global(.alert > :last-child) {
+    margin-bottom: 0;
+  }
+  .markdown :global(.alert-note) {
+    --alert-color: var(--color-feedback-info-text);
+  }
+  .markdown :global(.alert-tip) {
+    --alert-color: var(--color-feedback-success-text);
+  }
+  .markdown :global(.alert-important) {
+    --alert-color: var(--color-feedback-important-text);
+  }
+  .markdown :global(.alert-warning) {
+    --alert-color: var(--color-feedback-warning-text);
+  }
+  .markdown :global(.alert-caution) {
+    --alert-color: var(--color-feedback-error-text);
+  }
 </style>
 
 {#if frontMatter && frontMatter.length > 0}
diff --git a/src/lib/markdown.ts b/src/lib/markdown.ts
index 7206f673f..89f3e281c 100644
--- a/src/lib/markdown.ts
+++ b/src/lib/markdown.ts
@@ -98,6 +98,58 @@ const anchorMarkedExtension = {
   renderer: (token: Tokens.Generic): string => `<a name="${token.text}"></a>`,
 };
 
+// GitHub flavoured alerts: a blockquote whose first line is a `[!NOTE]` marker
+// renders as a titled callout rather than a quote.
+export const alertVariants = [
+  "note",
+  "tip",
+  "important",
+  "warning",
+  "caution",
+] as const;
+
+export type AlertVariant = (typeof alertVariants)[number];
+
+function isAlertVariant(name: string): name is AlertVariant {
+  return (alertVariants as readonly string[]).includes(name);
+}
+
+const alertMarkedExtension: TokenizerExtension & RendererExtension = {
+  name: "alert",
+  level: "block",
+  start: (src: string) => src.match(/^ {0,3}> *\[!/m)?.index,
+  tokenizer(src: string) {
+    const quote = /^(?: {0,3}>[^\n]*(?:\n|$))+/.exec(src);
+    if (!quote) {
+      return;
+    }
+
+    const body = quote[0].replace(/^ {0,3}> ?/gm, "");
+    const marker = /^\[!([a-zA-Z]+)\][^\S\n]*(?:\n|$)/.exec(body);
+    if (!marker) {
+      return;
+    }
+
+    const variant = marker[1].toLowerCase();
+    if (!isAlertVariant(variant)) {
+      return;
+    }
+
+    return {
+      type: "alert",
+      raw: quote[0],
+      variant,
+      tokens: this.lexer.blockTokens(body.slice(marker[0].length)),
+    };
+  },
+  renderer(token: Tokens.Generic): string {
+    const variant = token.variant as AlertVariant;
+    const title = variant.charAt(0).toUpperCase() + variant.slice(1);
+
+    return `<div class="alert alert-${variant}"><p class="alert-title">${title}</p>${this.parser.parse(token.tokens ?? [])}</div>`;
+  },
+};
+
 // Past this many references in one document the rest stay text, matching
 // the number of chips `Markdown` mounts.
 export const maximumReferences = 200;
@@ -180,7 +232,11 @@ export const markdownWithExtensions = new Marked(
   markedFootnote({ refMarkers: true }),
   markedEmoji({ emojis }),
   ((): MarkedExtension => ({
-    extensions: [anchorMarkedExtension, radicleReferenceMarkedExtension],
+    extensions: [
+      anchorMarkedExtension,
+      alertMarkedExtension,
+      radicleReferenceMarkedExtension,
+    ],
   }))(),
 );
 
diff --git a/tests/e2e/repo/markdownRendering.spec.ts b/tests/e2e/repo/markdownRendering.spec.ts
new file mode 100644
index 000000000..ed2290924
--- /dev/null
+++ b/tests/e2e/repo/markdownRendering.spec.ts
@@ -0,0 +1,29 @@
+import type { RadiclePeer } from "@tests/support/peerManager.js";
+
+import * as Fs from "node:fs/promises";
+import * as Path from "node:path";
+
+import { expect, test } from "@tests/support/fixtures.js";
+import { createRepo } from "@tests/support/repo.js";
+
+async function createRichRepo(peer: RadiclePeer) {
+  const { rid, repoFolder } = await createRepo(peer, { name: "rich" });
+  await Fs.writeFile(
+    Path.join(repoFolder, "README.md"),
+    ["# Rich", "", "> [!NOTE]", "> Read the guide first.", ""].join("\n"),
+  );
+  await peer.git(["add", "."], { cwd: repoFolder });
+  await peer.git(["commit", "-m", "Write a rich readme"], { cwd: repoFolder });
+  await peer.git(["push", "rad", "main"], { cwd: repoFolder });
+  return { rid };
+}
+
+test("render alerts in a readme", async ({ page, peer }) => {
+  const { rid } = await createRichRepo(peer);
+  await page.goto(`/repos/${rid}/home`);
+
+  const readme = page.locator(".markdown");
+  await expect(
+    readme.locator(".alert-note").getByText("Read the guide first."),
+  ).toBeVisible();
+});