hanna/fabrica

fix(web): rewrite relative README/markdown links into the repo

f0db157 · hanna committed on 2026-07-26

Relative links and images in a rendered README (or a previewed markdown file)
resolved against the current page URL, so `[cfg](fabrica.example.toml)` pointed
at `/owner/fabrica.example.toml` instead of the file. Rewrite them via comrak's
AST: links target the blob view and images the raw view, on the current ref,
resolving `./` and `../` from the document's directory. Absolute URLs, `//host`,
`mailto:`, and bare `#anchor` are left untouched.

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 +148 −5

crates/web/src/repo.rs +11 −5

 /// Render `source` markdown to sanitized, syntax-highlighted HTML.
 #[must_use]
 pub fn render(source: &str) -> Markup {
-    PreEscaped(render_html(source))
+    PreEscaped(render_html(source, None))
+}
 /// Like [`render`], but also linkifies `#123` issue/PR references against
 /// `repo_base` (e.g. `/owner/repo`). Used for issue/PR descriptions and comments.
 #[must_use]
 pub fn render_with_refs(source: &str, repo_base: &str) -> Markup {
-    PreEscaped(linkify_refs(&render_html(source), repo_base))
+    PreEscaped(linkify_refs(&render_html(source, None), repo_base))
+}
-/// The shared comrak + ammonia pipeline, producing sanitized HTML.
+/// Render a README or in-repo markdown file, rewriting **relative** links and
-fn render_html(source: &str) -> String {
+/// images so they point into the repository at `ref_name`. `base` is
+/// `/owner/repo`; `dir` is the directory the document lives in (empty for the
+/// repo root), used to resolve `./` and `../` paths. Also linkifies `#123`
+/// references. Absolute URLs, `//host`, `mailto:`, and `#anchor` are left alone.
+#[must_use]
+pub fn render_repo(source: &str, base: &str, ref_name: &str, dir: &str) -> Markup {
+    let repo = RepoUrls {
+        base,
+        ref_name,
+        dir,
+    };
+    PreEscaped(linkify_refs(&render_html(source, Some(&repo)), base))
+}
+/// The context for rewriting a repository document's relative URLs.
+struct RepoUrls<'a> {
+    base: &'a str,
+    ref_name: &'a str,
+    dir: &'a str,
+}
+impl RepoUrls<'_> {
+    /// Rewrite `url` to point into the repo, or `None` to leave it unchanged.
+    /// Links target the blob view; images target the raw view.
+    fn resolve(&self, url: &str, image: bool) -> Option<String> {
+        let url = url.trim();
+        if url.is_empty()
+            || url.starts_with('#')
+            || url.starts_with("//")
+            || url.starts_with("mailto:")
+        {
+            return None;
+        }
+        // A scheme (`https:`, `data:`, …) marks an absolute URL — leave it be.
+        if let Some(idx) = url.find(':')
+            && url[..idx]
+                .chars()
+                .all(|c| c.is_ascii_alphanumeric() || matches!(c, '+' | '-' | '.'))
+            && !url[..idx].is_empty()
+        {
+            return None;
+        }
+        // Split off a trailing `?query` / `#fragment` to reattach after resolving.
+        let (path, suffix) = url
+            .find(['?', '#'])
+            .map_or((url, ""), |i| (&url[..i], &url[i..]));
+        let joined = if let Some(root_rel) = path.strip_prefix('/') {
+            root_rel.to_string()
+        } else if self.dir.is_empty() {
+            path.to_string()
+        } else {
+            format!("{}/{path}", self.dir)
+        };
+        let resolved = normalize_path(&joined);
+        let view = if image { "raw" } else { "blob" };
+        Some(format!(
+            "{}/-/{view}/{}/{resolved}{suffix}",
+            self.base, self.ref_name
+        ))
+    }
+}
+/// Resolve `.`/`..`/empty segments in a slash path (no leading slash on output).
+fn normalize_path(path: &str) -> String {
+    let mut out: Vec<&str> = Vec::new();
+    for seg in path.split('/') {
+        match seg {
+            "" | "." => {}
+            ".." => {
+                out.pop();
+            }
+            other => out.push(other),
+        }
+    }
+    out.join("/")
+}
+/// Rewrite every relative link and image URL in the AST subtree.
+fn rewrite_urls<'a>(node: &'a comrak::nodes::AstNode<'a>, repo: &RepoUrls) {
+    for child in node.children() {
+        rewrite_urls(child, repo);
+    }
+    let mut data = node.data.borrow_mut();
+    match &mut data.value {
+        comrak::nodes::NodeValue::Link(link) => {
+            if let Some(url) = repo.resolve(&link.url, false) {
+                link.url = url;
+            }
+        }
+        comrak::nodes::NodeValue::Image(link) => {
+            if let Some(url) = repo.resolve(&link.url, true) {
+                link.url = url;
+            }
+        }
+        _ => {}
+    }
+}
+/// The shared comrak + ammonia pipeline, producing sanitized HTML. When `repo`
+/// is set, relative links/images are rewritten into the repository first.
+fn render_html(source: &str, repo: Option<&RepoUrls>) -> String {
     let mut options = comrak::Options::default();
     options.extension.table = true;
     options.extension.strikethrough = true;
     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 unsafe_html = match repo {
+        None => comrak::markdown_to_html_with_plugins(source, &options, &plugins),
+        Some(repo) => {
+            let arena = comrak::Arena::new();
+            let root = comrak::parse_document(&arena, source, &options);
+            rewrite_urls(root, repo);
+            let mut out = String::new();
+            let _ = comrak::format_html_with_plugins(root, &options, &mut out, &plugins);
+            out
+        }
+    };
     sanitizer().clean(&unsafe_html).to_string()
+}
+    }
     #[test]
+    fn rewrites_relative_repo_links_and_images() {
+        let src = "[cfg](fabrica.example.toml) ![logo](docs/logo.png) \
+                   [abs](https://x.test/y) [anchor](#s)";
+        let html = render_repo(src, "/hanna/fabrica", "main", "").into_string();
+        // A relative link points at the blob view on the current ref.
+        assert!(
+            html.contains(r#"href="/hanna/fabrica/-/blob/main/fabrica.example.toml""#),
+            "relative link rewritten: {html}"
+        );
+        // A relative image points at the raw view.
+        assert!(
+            html.contains(r#"src="/hanna/fabrica/-/raw/main/docs/logo.png""#),
+            "relative image rewritten: {html}"
+        );
+        // Absolute URLs and bare anchors are left untouched.
+        assert!(
+            html.contains(r#"href="https://x.test/y""#),
+            "abs kept: {html}"
+        );
+        assert!(html.contains(r##"href="#s""##), "anchor kept: {html}");
+    }
+    #[test]
+    fn resolves_relative_paths_from_the_document_directory() {
+        // A link in docs/guide.md to ../README.md resolves to the repo root.
+        let html = render_repo("[up](../README.md)", "/o/r", "v1.0", "docs").into_string();
+        assert!(
+            html.contains(r#"href="/o/r/-/blob/v1.0/README.md""#),
+            "../ resolved against dir: {html}"
+        );
+    }
+    #[test]
     fn highlights_fenced_code() {
         let html = render("```rust\nfn main() {}\n```").into_string();
         // A keyword span survives sanitizing with its highlight class.

     rev: &git::Resolved,
     branches: &[String],
 ) -> AppResult<Markup> {
+    let base = format!("/{}/{}", ctx.owner.username, ctx.repo.path);
     let entries = git_read(state, &ctx.repo.id, {
         let rev = rev.clone();
         move |repo| repo.tree_entries(&rev, FsPath::new(""))
     })
     .await?;
-    let readme = load_readme(state, &ctx.repo.id, rev, &entries).await;
+    let readme = load_readme(state, &ctx.repo.id, rev, &entries, &base, rev_name).await;
     let annotations = git_read(state, &ctx.repo.id, {
         let rev = rev.clone();
         move |repo| repo.tree_annotations(&rev, FsPath::new(""))
     .await
     .map(|files| crate::languages::breakdown(&files))
     .unwrap_or_default();
-    let base = format!("/{}/{}", ctx.owner.username, ctx.repo.path);
     Ok(html! {
         (repo_header(state, ctx, Tab::Code, rev_name, branches))
         form class="search-row repo-codesearch" method="get" action=(format!("{base}/-/search")) {
     })
+}
-/// Find and render the first matching README in the root tree.
+/// Find and render the first matching README in the root tree, rewriting its
+/// relative links/images into the repo at `ref_name`.
 async fn load_readme(
     state: &AppState,
     repo_id: &str,
     rev: &git::Resolved,
     entries: &[git::TreeEntry],
+    base: &str,
+    ref_name: &str,
 ) -> Option<Markup> {
     let name = README_NAMES.iter().find(|candidate| {
         entries
         return None;
+    }
     let text = String::from_utf8_lossy(&blob.content);
-    Some(markdown::render(&text))
+    // The README lives at the repo root, so relative paths resolve from "".
+    Some(markdown::render_repo(&text, base, ref_name, ""))
+}
 /// The "empty repository" landing with clone instructions.
                 p { a class="btn" href=(raw_url) { "Download" } }
+            }
         } @else if show_preview {
+            // Relative links in the file resolve from its own directory.
+            @let dir = path.rsplit_once('/').map_or("", |(d, _)| d);
             div class="blob-preview markdown" {
-                (markdown::render(&String::from_utf8_lossy(&blob.content)))
+                (markdown::render_repo(&String::from_utf8_lossy(&blob.content), &base, rev_name, dir))
+            }
         } @else {
             (highlighted_code(FsPath::new(path), &blob.content, attr_lang))