hanna/fabrica

feat(web): syntax-highlight fenced code blocks in markdown

8263389 · hanna committed on 2026-07-25

Bridge comrak's code-fence rendering to the highlight crate via a
SyntaxHighlighterAdapter, so README/bio code blocks get the same hl-* theme
classes as the blob viewer. The ammonia sanitizer is extended to permit only
those highlight classes; unknown or plain fences fall back to escaped text.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

crates/web/src/markdown.rs +116 −8

 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-//! Markdown rendering for READMEs.
+//! Markdown rendering for READMEs and bios.
 //!
-//! `comrak` with the GFM extensions renders the source; `ammonia` then sanitizes
+//! `comrak` with the GFM extensions renders the source; a
-//! the result, stripping raw HTML and any scripting so a README can never inject
+//! [`SyntaxHighlighterAdapter`] runs fenced code blocks through the `highlight`
-//! markup into the page. Relative-link rewriting and fenced-code highlighting are
+//! crate so they get the same `hl-*` theme classes as the blob viewer; then
-//! deferred to the polish phase.
+//! `ammonia` sanitizes the result, stripping raw HTML and scripting while
+//! permitting only our highlight classes, so a README can never inject markup.
+use std::borrow::Cow;
+use std::collections::HashMap;
+use std::fmt::{self, Write as _};
+use std::path::Path as FsPath;
+use comrak::adapters::SyntaxHighlighterAdapter;
 use maud::{Markup, PreEscaped};
-/// Render `source` markdown to sanitized HTML, ready to splice into a page.
+/// Render `source` markdown to sanitized, syntax-highlighted HTML.
 #[must_use]
 pub fn render(source: &str) -> Markup {
     let mut options = comrak::Options::default();
     options.extension.autolink = true;
     options.extension.footnotes = true;
-    let unsafe_html = comrak::markdown_to_html(source, &options);
+    let adapter = Highlighter;
-    let safe = ammonia::clean(&unsafe_html);
+    let mut plugins = comrak::options::Plugins::default();
+    plugins.render.codefence_syntax_highlighter = Some(&adapter);
+    let unsafe_html = comrak::markdown_to_html_with_plugins(source, &options, &plugins);
+    let safe = sanitizer().clean(&unsafe_html).to_string();
     PreEscaped(safe)
+}
+/// The ammonia sanitizer, extended to allow the highlighter's `<span class="hl-*">`
+/// runs (and only those classes) inside code blocks.
+fn sanitizer() -> ammonia::Builder<'static> {
+    let mut builder = ammonia::Builder::default();
+    builder.add_tags(["span"]);
+    builder.add_allowed_classes("span", highlight::HL_CLASSES.iter().copied());
+    builder.add_allowed_classes("code", ["highlight"]);
+    builder
+}
+/// Bridges comrak's code-fence rendering to the `highlight` crate.
+struct Highlighter;
+impl SyntaxHighlighterAdapter for Highlighter {
+    fn write_highlighted(
+        &self,
+        output: &mut dyn fmt::Write,
+        lang: Option<&str>,
+        code: &str,
+    ) -> fmt::Result {
+        // The info string is a language hint (like a `.gitattributes` override);
+        // resolve it, then highlight. Unknown/plain langs fall back to escaped text.
+        let hint = lang.map(str::trim).filter(|l| !l.is_empty());
+        let resolved = highlight::resolve(FsPath::new(""), code.as_bytes(), hint);
+        let lines = highlight::highlight_document(&resolved, code);
+        for (i, line) in lines.iter().enumerate() {
+            if i > 0 {
+                output.write_char('\n')?;
+            }
+            for span in &line.spans {
+                match span.class {
+                    Some(class) => {
+                        write!(
+                            output,
+                            "<span class=\"{class}\">{}</span>",
+                            Escape(&span.text)
+                        )?;
+                    }
+                    None => write!(output, "{}", Escape(&span.text))?,
+                }
+            }
+        }
+        Ok(())
+    }
+    fn write_pre_tag(
+        &self,
+        output: &mut dyn fmt::Write,
+        _attributes: HashMap<&'static str, Cow<'_, str>>,
+    ) -> fmt::Result {
+        output.write_str("<pre>")
+    }
+    fn write_code_tag(
+        &self,
+        output: &mut dyn fmt::Write,
+        _attributes: HashMap<&'static str, Cow<'_, str>>,
+    ) -> fmt::Result {
+        output.write_str("<code class=\"highlight\">")
+    }
+}
+/// A `Display` wrapper that HTML-escapes text as it is written.
+struct Escape<'a>(&'a str);
+impl fmt::Display for Escape<'_> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        for c in self.0.chars() {
+            match c {
+                '&' => f.write_str("&amp;")?,
+                '<' => f.write_str("&lt;")?,
+                '>' => f.write_str("&gt;")?,
+                '"' => f.write_str("&quot;")?,
+                _ => f.write_char(c)?,
+            }
+        }
+        Ok(())
+    }
+}
 #[cfg(test)]
 mod tests {
     use super::*;
         let html = render("| a | b |\n| - | - |\n| 1 | 2 |").into_string();
         assert!(html.contains("<table>"));
+    }
+    #[test]
+    fn highlights_fenced_code() {
+        let html = render("```rust\nfn main() {}\n```").into_string();
+        // A keyword span survives sanitizing with its highlight class.
+        assert!(
+            html.contains("hl-keyword"),
+            "fenced rust should be highlighted: {html}"
+        );
+        assert!(!html.contains("<script"));
+    }
+    #[test]
+    fn plain_fence_is_escaped_not_highlighted() {
+        let html = render("```\n<b>x</b> & y\n```").into_string();
+        assert!(html.contains("&lt;b&gt;"), "code is escaped: {html}");
+    }
+}