feat(pdf): render PDF hyperlink annotations as Markdown links in strict mode

The standard docling PDF pipeline discards link annotations, so emitting
them would break byte-for-byte conformance. This adds them to the Rust-only
`strict(true)` output only — legacy/docling output (and the 4/14 groundtruth
conformance + 91/91 snapshot baseline) is left untouched.

- pdfium_backend: extract per-page link annotations (rect + URI), restricted
  to web/mailto/tel schemes, into `PdfPage.links`.
- assemble: resolve each link rect to the visible anchor text via per-word
  cells (line-merged cells would over-capture a whole line), cleaned the same
  way prose is; accumulate `(anchor, href)` onto the document in reading order.
- core: `DoclingDocument.links` + a strict-only serializer pass that wraps each
  anchor as `[anchor](href)`, matching the body's HTML-escaped form and
  consuming repeated anchors in document order.

Verified on a real CV PDF: LinkedIn/GitHub/email/cert links render in strict
mode; default output has none.

Note: this does not change PDF conformance (still 4/14). The remaining
near-misses (RTL justified-space reconstruction, two-column figure-overflow
reading order, TableFormer multi-row headers, layout misclassification) are
model-level and not safe quick fixes; documented in PDF_CONFORMANCE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012RkJ8nFxQQB2Qn3sTgg8hT

Author: claude

COMPARING.md

@@ -273,8 +273,9 @@ tail of docling-specific quirks (below), each typically 1–2 lines.
 > These numbers are for **legacy** mode (`DocumentConverter::new()`), which aims
 > for byte-for-byte docling output. The Rust-only `strict(true)` mode instead
 > emits cleaner Markdown (code-fence languages kept, no `***x*** .` run-spacing,
-> no `\_`/entity re-escaping) — it deliberately *diverges* from docling, so don't
-> measure conformance against it.
+> no `\_`/entity re-escaping, and **PDF hyperlink annotations rendered as
+> `[anchor](href)`** — web/mail/tel targets that docling's pipeline drops) — it
+> deliberately *diverges* from docling, so don't measure conformance against it.
 
 ### HTML
 

crates/fleischwolf-core/src/document.rs

@@ -24,6 +24,12 @@ pub struct DoclingDocument {
     /// (its committed groundtruth corpus predates the padded serializer); DOCX/HTML
     /// leave it `false` to match current published docling.
     pub compact_tables: bool,
+    /// Hyperlinks recovered from the source, as `(anchor_text, href)` pairs in
+    /// document order. docling's standard pipeline drops PDF link annotations, so
+    /// these are rendered as Markdown `[anchor](href)` **only in strict mode**
+    /// (legacy/docling output is left byte-for-byte unchanged). The PDF backend
+    /// populates this from pdfium link annotations; other backends leave it empty.
+    pub links: Vec<(String, String)>,
 }
 
 /// A single piece of document content.
@@ -98,6 +104,7 @@ impl DoclingDocument {
             nodes: Vec::new(),
             strict_markdown: false,
             compact_tables: false,
+            links: Vec::new(),
         }
     }
 

crates/fleischwolf-core/src/markdown.rs

@@ -55,7 +55,13 @@ pub fn to_markdown_images(
     };
     let mut blocks: Vec<String> = Vec::new();
     render(&doc.nodes, &mut blocks, &mut ctx);
-    let body = blocks.join("\n\n");
+    let mut body = blocks.join("\n\n");
+    // Strict mode only: turn recovered source hyperlinks into Markdown links.
+    // docling's standard pipeline drops them, so doing this in legacy mode would
+    // diverge from docling — hence strict-only, leaving conformance output intact.
+    if strict && !doc.links.is_empty() {
+        body = apply_links(&body, &doc.links);
+    }
     let md = if body.is_empty() {
         String::new()
     } else {
@@ -64,6 +70,35 @@ pub fn to_markdown_images(
     (md, ctx.artifacts)
 }
 
+/// Wrap each recovered link's anchor text in Markdown `[anchor](href)`. Anchors
+/// arrive cleaned (curly quotes/dashes already normalized) but un-escaped, so we
+/// match against the body's HTML-escaped (`&`/`<`/`>`) form, the way prose nodes
+/// were serialized. Links are consumed in document order from a moving cursor, so
+/// a repeated anchor (e.g. two "issues") links its successive occurrences rather
+/// than all pointing at the first. An anchor that can't be located is skipped
+/// (its text may have been split across a line wrap or table cell).
+fn apply_links(body: &str, links: &[(String, String)]) -> String {
+    let mut out = body.to_string();
+    let mut cursor = 0usize;
+    for (anchor, href) in links {
+        let anchor = anchor
+            .replace('&', "&amp;")
+            .replace('<', "&lt;")
+            .replace('>', "&gt;");
+        if anchor.is_empty() {
+            continue;
+        }
+        if let Some(rel) = out[cursor..].find(&anchor) {
+            let at = cursor + rel;
+            // Don't relink inside an already-emitted `](` Markdown link target.
+            let replacement = format!("[{anchor}]({href})");
+            out.replace_range(at..at + anchor.len(), &replacement);
+            cursor = at + replacement.len();
+        }
+    }
+    out
+}
+
 /// In `strict` mode, rewrite inline text for readability rather than byte-for-byte
 /// docling fidelity: undo the legacy `\_` underscore escaping, and tighten stray
 /// spaces around punctuation (`[ 37 , 36 ]` → `[37, 36]`, `( x )` → `(x)`). This
@@ -364,6 +399,41 @@ mod tests {
         assert_eq!(md, "# Title\n\nHello world.\n\n- first\n- second\n");
     }
 
+    #[test]
+    fn strict_renders_recovered_links_legacy_does_not() {
+        let mut doc = DoclingDocument::new("cv");
+        doc.add_paragraph("Find me on LinkedIn or GitHub.");
+        doc.links = vec![
+            ("LinkedIn".into(), "https://www.linkedin.com/in/x/".into()),
+            ("GitHub".into(), "https://github.com/x/".into()),
+        ];
+        // Legacy/docling mode: links are left untouched (conformance preserved).
+        assert_eq!(doc.export_to_markdown(), "Find me on LinkedIn or GitHub.\n");
+        // Strict mode: anchors become Markdown links.
+        assert_eq!(
+            doc.export_to_markdown_with(true),
+            "Find me on [LinkedIn](https://www.linkedin.com/in/x/) or [GitHub](https://github.com/x/).\n"
+        );
+    }
+
+    #[test]
+    fn strict_links_match_escaped_anchor_and_consume_in_order() {
+        let mut doc = DoclingDocument::new("d");
+        // The PDF assembler HTML-escapes prose, so by serialization time the body
+        // already carries `&amp;`; the anchor is stored un-escaped. The matcher must
+        // escape the anchor to find it. Two identical anchors link in document order.
+        doc.add_paragraph("AI &amp; ML here, and issues here, then issues there.");
+        doc.links = vec![
+            ("AI & ML".into(), "https://a/".into()),
+            ("issues".into(), "https://first/".into()),
+            ("issues".into(), "https://second/".into()),
+        ];
+        assert_eq!(
+            doc.export_to_markdown_with(true),
+            "[AI &amp; ML](https://a/) here, and [issues](https://first/) here, then [issues](https://second/) there.\n"
+        );
+    }
+
     #[test]
     fn renders_compact_table() {
         let mut doc = DoclingDocument::new("t");

crates/fleischwolf-pdf/src/assemble.rs

@@ -224,6 +224,58 @@ fn fix_arabic_lam_alef(s: &str) -> String {
     out.into_iter().collect()
 }
 
+/// Resolve each page hyperlink to the visible text it covers, as `(anchor, uri)`
+/// in reading order. The anchor is the cells whose centre falls in the link rect,
+/// joined left-to-right and cleaned the same way prose is (so it matches the
+/// serialized text), deduped against the immediately-preceding link so pdfium's
+/// occasional duplicate annotation doesn't double-list. Empty anchors are dropped.
+pub(crate) fn resolve_link_anchors(page: &PdfPage) -> Vec<(String, String)> {
+    let mut out: Vec<(String, String)> = Vec::new();
+    // Use per-word cells, not the line-merged `cells`: a link rect covers a few
+    // words on a line, and a whole merged line cell would over-capture (its centre
+    // lands in one link's rect, grabbing the entire line as that link's anchor).
+    let words = if page.word_cells.is_empty() {
+        &page.cells
+    } else {
+        &page.word_cells
+    };
+    for link in &page.links {
+        let mut inside: Vec<&TextCell> = words
+            .iter()
+            .filter(|c| {
+                let (cx, cy) = ((c.l + c.r) / 2.0, (c.t + c.b) / 2.0);
+                cx >= link.l && cx <= link.r && cy >= link.t && cy <= link.b
+            })
+            .collect();
+        // Reading order: top band then left-to-right (link anchors are LTR).
+        let band = inside
+            .iter()
+            .map(|c| (c.b - c.t).abs())
+            .fold(0.0f32, f32::max)
+            .max(1.0);
+        inside.sort_by_key(|c| ((c.t / band).round() as i64, (c.l * 10.0) as i64));
+        let anchor = clean_text(
+            &inside
+                .iter()
+                .map(|c| c.text.trim())
+                .filter(|t| !t.is_empty())
+                .collect::<Vec<_>>()
+                .join(" "),
+        );
+        if anchor.is_empty() {
+            continue;
+        }
+        if out
+            .last()
+            .is_some_and(|(a, u)| a == &anchor && u == &link.uri)
+        {
+            continue;
+        }
+        out.push((anchor, link.uri.clone()));
+    }
+    out
+}
+
 /// Cells assigned to a region (best container), in reading order, joined.
 fn region_text(region: &Region, cells: &[TextCell]) -> String {
     let mut inside: Vec<&TextCell> = cells
@@ -483,6 +535,8 @@ pub fn assemble_page(
     table_rows: &[Option<Vec<Vec<String>>>],
     doc: &mut DoclingDocument,
 ) {
+    // Recover this page's hyperlinks (rendered only in strict Markdown).
+    doc.links.extend(resolve_link_anchors(page));
     // Pair each region with its precomputed TableFormer grid (indexed by original
     // order) and order by reading order together, so they stay aligned.
     let mut items: Vec<(Region, Option<Vec<Vec<String>>>)> = regions

crates/fleischwolf-pdf/src/lib.rs

@@ -129,6 +129,7 @@ impl Pipeline {
             code_cells: Vec::new(),
             word_cells: Vec::new(),
             image,
+            links: Vec::new(),
         };
         self.process_pages(vec![page], name)
     }

crates/fleischwolf-pdf/src/mets.rs

@@ -72,6 +72,7 @@ pub fn convert_mets_gbs(bytes: &[u8], name: &str) -> Result<DoclingDocument, Pdf
             code_cells: Vec::new(),
             word_cells: Vec::new(),
             image,
+            links: Vec::new(),
         });
     }
     if pages.is_empty() {

crates/fleischwolf-pdf/src/pdfium_backend.rs

@@ -45,6 +45,20 @@ pub struct PdfPage {
     /// matching.
     pub word_cells: Vec<TextCell>,
     pub image: RgbImage,
+    /// Hyperlink annotations on the page (rect in top-left page coords + target
+    /// URI), restricted to web/mail/tel schemes. Used only by strict Markdown.
+    pub links: Vec<LinkAnnot>,
+}
+
+/// A PDF link annotation: its rectangle (top-left page coordinates, matching
+/// [`TextCell`]) and target URI.
+#[derive(Debug, Clone)]
+pub struct LinkAnnot {
+    pub l: f32,
+    pub t: f32,
+    pub r: f32,
+    pub b: f32,
+    pub uri: String,
 }
 
 /// A parsed PDF: per-page text cells and page images.
@@ -152,9 +166,43 @@ fn extract_page(
         code_cells,
         word_cells,
         image,
+        links: extract_links(page, height),
     })
 }
 
+/// Collect web/mail/tel hyperlink annotations on a page, mapping each link's
+/// rectangle into top-left page coordinates (like [`TextCell`]). `file://` and
+/// in-document destinations are skipped — only externally meaningful targets are
+/// rendered. pdfium occasionally lists a link twice; rects are kept as-is and the
+/// caller dedupes by resolved anchor text.
+fn extract_links(page: &pdfium_render::prelude::PdfPage<'_>, page_h: f32) -> Vec<LinkAnnot> {
+    let mut out = Vec::new();
+    for link in page.links().iter() {
+        let Some(uri) = link
+            .action()
+            .and_then(|a| a.as_uri_action().and_then(|u| u.uri().ok()))
+        else {
+            continue;
+        };
+        let scheme_ok = ["http://", "https://", "mailto:", "tel:"]
+            .iter()
+            .any(|s| uri.starts_with(s));
+        if !scheme_ok {
+            continue;
+        }
+        if let Ok(rect) = link.rect() {
+            out.push(LinkAnnot {
+                l: rect.left().value,
+                t: page_h - rect.top().value,
+                r: rect.right().value,
+                b: page_h - rect.bottom().value,
+                uri,
+            });
+        }
+    }
+    out
+}
+
 /// Fallback line cells from pdfium-render's style segments (one cell per
 /// segment). Used only when the raw-FFI text page can't be loaded.
 fn segment_cells(text: &PdfPageText, page_h: f32) -> Vec<TextCell> {