html-to-markdown 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7681da88f184d981337443e5fd5ba46746c3d51690aea94cd4ed33a903081996
-  data.tar.gz: e0073d5087e894e76588d03853f94d618412e650d8d3c6b62831555ede8f5230
+  metadata.gz: c23b51454716c4f5224bc9a0b6cfcfcf3f9935709379395662d9d89cab96f223
+  data.tar.gz: '0878f8bad06ca970013d87f6064150bed2db8b5e12d087474acaa4dd17a00559'
 SHA512:
-  metadata.gz: 94d123fc5f89d7d83ed6e05feed6fe9d6a084822d42c257a41e2af2bfdde92905f852956dea05e924483284b1fde84eaf1b0e0230ab542c5db56fd64d5a553bf
-  data.tar.gz: e474ddd110717cada39806796d8c7b1a2bd8900193d4413058392f69424ca7a964c3fa9b41feed493526ccbb6d7f3a6c36d3cc0553504c28c6933488abdbe9a9
+  metadata.gz: e21bd6d2ec9cbd40df454f2b441cb2da333b1c73a062686f830c4bd3368dad2dacec3bb0953f5c8902ad2ab411453c690597d64f0c86103d65b71438c647a7f1
+  data.tar.gz: 38cf61f5035e6becae227f4117f10208eb9b0ca2d99b805b6e8feefdc8bf2611e44605c967218ea69892df3af8a417026fb70e20cb3ab9a9e28771c3ecc723c9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    html-to-markdown (3.0.1)
+    html-to-markdown (3.1.0)
       rb_sys (>= 0.9, < 1.0)
 
 GEM
@@ -29,6 +29,7 @@ GEM
     diff-lcs (1.6.2)
     drb (2.2.3)
     ffi (1.17.4-arm64-darwin)
+    ffi (1.17.4-x86_64-linux-gnu)
     fileutils (1.8.0)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
@@ -40,7 +41,7 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
-    minitest (6.0.2)
+    minitest (6.0.3)
       drb (~> 2.0)
       prism (~> 1.5)
     mutex_m (0.3.0)
@@ -58,7 +59,8 @@ GEM
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rb_sys (0.9.124)
+    rb_sys (0.9.125)
+      json (>= 2)
       rake-compiler-dock (= 1.11.0)
     rbs (3.10.4)
       logger
@@ -126,6 +128,7 @@ GEM
 
 PLATFORMS
   arm64-darwin
+  x86_64-linux
 
 DEPENDENCIES
   html-to-markdown!
@@ -148,15 +151,16 @@ CHECKSUMS
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   ffi (1.17.4-arm64-darwin) sha256=19071aaf1419251b0a46852abf960e77330a3b334d13a4ab51d58b31a937001b
+  ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d
   fileutils (1.8.0) sha256=8c6b1df54e2540bdb2f39258f08af78853aa70bad52b4d394bbc6424593c6e02
-  html-to-markdown (3.0.1)
+  html-to-markdown (3.1.0)
   i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
   json (2.19.3) sha256=289b0bb53052a1fa8c34ab33cc750b659ba14a5c45f3fcf4b18762dc67c78646
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
   listen (3.10.0) sha256=c6e182db62143aeccc2e1960033bebe7445309c7272061979bb098d03760c9d2
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
-  minitest (6.0.2) sha256=db6e57956f6ecc6134683b4c87467d6dd792323c7f0eea7b93f66bd284adbc3d
+  minitest (6.0.3) sha256=88ac8a1de36c00692420e7cb3cc11a0773bbcb126aee1c249f320160a7d11411
   mutex_m (0.3.0) sha256=cfcb04ac16b69c4813777022fdceda24e9f798e48092a2b817eb4c0a782b0751
   parallel (1.27.0) sha256=4ac151e1806b755fb4e2dc2332cbf0e54f2e24ba821ff2d3dcf86bf6dc4ae130
   parser (3.3.11.1) sha256=d17ace7aabe3e72c3cc94043714be27cc6f852f104d81aa284c2281aecc65d54
@@ -168,7 +172,7 @@ CHECKSUMS
   rake-compiler-dock (1.11.0) sha256=eab51f2cd533eb35cea6b624a75281f047123e70a64c58b607471bb49428f8c2
   rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe
   rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e
-  rb_sys (0.9.124) sha256=513476557b12eaf73764b3da9f8746024558fe8699bda785fb548c9aa3877ae7
+  rb_sys (0.9.125) sha256=14efd4e07eaf7c07edb1bab548d2a4767869a47a8821fc5ea52d9bf982ef00a8
   rbs (3.10.4) sha256=b17d7c4be4bb31a11a3b529830f0aa206a807ca42f2e7921a3027dfc6b7e5ce8
   regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
   rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587

data/README.md

@@ -18,7 +18,7 @@
     <img src="https://img.shields.io/maven-central/v/dev.kreuzberg/html-to-markdown?label=Java&color=007ec6" alt="Java">
   </a>
   <a href="https://pkg.go.dev/github.com/kreuzberg-dev/html-to-markdown/packages/go/v3/htmltomarkdown">
-    <img src="https://img.shields.io/github/v/tag/kreuzberg-dev/html-to-markdown?label=Go&color=007ec6&filter=v3.0.1" alt="Go">
+    <img src="https://img.shields.io/github/v/tag/kreuzberg-dev/html-to-markdown?label=Go&color=007ec6&filter=v3.1.0" alt="Go">
   </a>
   <a href="https://www.nuget.org/packages/KreuzbergDev.HtmlToMarkdown/">
     <img src="https://img.shields.io/nuget/v/KreuzbergDev.HtmlToMarkdown?label=C%23&color=007ec6" alt="C#">

data/ext/html-to-markdown-rb/native/Cargo.lock

@@ -59,16 +59,14 @@ checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
 [[package]]
 name = "bindgen"
-version = "0.69.5"
+version = "0.72.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "271383c67ccabffb7381723dea0672a673f292304fcb45c01cc648c7a8d58088"
+checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
 dependencies = [
  "bitflags",
  "cexpr",
  "clang-sys",
  "itertools",
- "lazy_static",
- "lazycell",
  "proc-macro2",
  "quote",
  "regex",
@@ -260,7 +258,7 @@ dependencies = [
 
 [[package]]
 name = "html-to-markdown-rb"
-version = "3.0.0"
+version = "3.0.1"
 dependencies = [
  "html-to-markdown-rs",
  "magnus",
@@ -269,7 +267,7 @@ dependencies = [
 
 [[package]]
 name = "html-to-markdown-rs"
-version = "3.0.0"
+version = "3.0.1"
 dependencies = [
  "ahash",
  "astral-tl",
@@ -326,9 +324,9 @@ dependencies = [
 
 [[package]]
 name = "itertools"
-version = "0.12.1"
+version = "0.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ba291022dbbd398a455acf126c1e341954079855bc60dfdda641363bd6922569"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
 dependencies = [
  "either",
 ]
@@ -345,12 +343,6 @@ version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
 
-[[package]]
-name = "lazycell"
-version = "1.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "830d08ce1d1d941e6b30645f1a0eb5643013d835ce3779a5fc208261dbe10f55"
-
 [[package]]
 name = "libc"
 version = "0.2.183"
@@ -609,18 +601,18 @@ dependencies = [
 
 [[package]]
 name = "rb-sys"
-version = "0.9.124"
+version = "0.9.125"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c85c4188462601e2aa1469def389c17228566f82ea72f137ed096f21591bc489"
+checksum = "85b37650fabd8ba515910a0dc089dcb6348eb3c35fbf91698cb226435be2babc"
 dependencies = [
  "rb-sys-build",
 ]
 
 [[package]]
 name = "rb-sys-build"
-version = "0.9.124"
+version = "0.9.125"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "568068db4102230882e6d4ae8de6632e224ca75fe5970f6e026a04e91ed635d3"
+checksum = "c73b806faa66006e491458b48a78725621c1ac5a2a6efe2614c90711a7780b80"
 dependencies = [
  "bindgen",
  "lazy_static",
@@ -677,9 +669,9 @@ checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
 
 [[package]]
 name = "rustc-hash"
-version = "1.1.0"
+version = "2.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2"
+checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
 
 [[package]]
 name = "scopeguard"

data/ext/html-to-markdown-rb/native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "html-to-markdown-rb"
-version = "3.0.1"
+version = "3.1.0"
 edition = "2024"
 authors = ["Na'aman Hirschfeld <naaman@kreuzberg.dev>"]
 license = "MIT"

data/lib/html_to_markdown/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HtmlToMarkdown
-  VERSION = '3.0.1'
+  VERSION = '3.1.0'
 end

data/vendor/Cargo.toml

@@ -3,7 +3,7 @@ members = ["html-to-markdown-rs"]
 resolver = "2"
 
 [workspace.package]
-version = "3.0.1"
+version = "3.1.0"
 edition = "2024"
 rust-version = "1.85"
 authors = ["Na'aman Hirschfeld <naaman@kreuzberg.dev>"]

data/vendor/html-to-markdown-rs/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "html-to-markdown-rs"
-version = "3.0.1"
+version = "3.1.0"
 edition = "2024"
 authors = ["Na'aman Hirschfeld <naaman@kreuzberg.dev>"]
 license = "MIT"

data/vendor/html-to-markdown-rs/src/converter/block/heading.rs

@@ -128,16 +128,20 @@ pub(crate) fn handle(
         }
 
         // Notify the structure collector if present.
-        if let Some(ref sc) = ctx.structure_collector {
-            if let Some(node) = node_handle.get(parser) {
-                if let tl::Node::Tag(tag) = node {
-                    let id = tag
-                        .attributes()
-                        .get("id")
-                        .flatten()
-                        .map(|v| v.as_utf8_str().to_string());
-                    sc.borrow_mut()
-                        .push_heading(level as u8, normalized.as_ref(), id.as_deref());
+        // Skip headings inside table cells — they are part of the table content,
+        // not standalone structural headings.
+        if !ctx.in_table_cell {
+            if let Some(ref sc) = ctx.structure_collector {
+                if let Some(node) = node_handle.get(parser) {
+                    if let tl::Node::Tag(tag) = node {
+                        let id = tag
+                            .attributes()
+                            .get("id")
+                            .flatten()
+                            .map(|v| v.as_utf8_str().to_string());
+                        sc.borrow_mut()
+                            .push_heading(level as u8, normalized.as_ref(), id.as_deref());
+                    }
                 }
             }
         }

data/vendor/html-to-markdown-rs/src/converter/context.rs

@@ -12,6 +12,7 @@ use std::rc::Rc;
 #[cfg(feature = "inline-images")]
 use crate::inline_images::InlineImageCollector;
 
+use crate::converter::reference_collector::ReferenceCollectorHandle;
 use crate::types::structure_collector::StructureCollectorHandle;
 
 /// Handle type for inline image collector when feature is enabled.
@@ -105,6 +106,8 @@ pub struct Context {
     ///
     /// Populated when `options.include_document_structure == true`.
     pub(crate) structure_collector: Option<StructureCollectorHandle>,
+    /// Optional reference collector for reference-style links.
+    pub(crate) reference_collector: Option<ReferenceCollectorHandle>,
 }
 
 impl Context {
@@ -122,6 +125,7 @@ impl Context {
         #[cfg(feature = "visitor")] visitor: Option<crate::visitor::VisitorHandle>,
         #[cfg(not(feature = "visitor"))] _visitor: Option<()>,
         structure_collector: Option<StructureCollectorHandle>,
+        reference_collector: Option<ReferenceCollectorHandle>,
     ) -> Self {
         #[cfg(feature = "metadata")]
         let (
@@ -186,6 +190,7 @@ impl Context {
             #[cfg(feature = "visitor")]
             visitor_error: Rc::new(RefCell::new(None)),
             structure_collector,
+            reference_collector,
         }
     }
 }

data/vendor/html-to-markdown-rs/src/converter/handlers/code_block.rs

@@ -301,6 +301,10 @@ pub fn handle_pre(
         {
             format_code_block(&processed_content, language.as_deref(), output, options, ctx);
         }
+
+        if let Some(ref sc) = ctx.structure_collector {
+            sc.borrow_mut().push_code(&processed_content, language.as_deref());
+        }
     }
 }
 

data/vendor/html-to-markdown-rs/src/converter/handlers/graphic.rs

@@ -128,6 +128,8 @@ pub fn handle_graphic(
                 &alt,
                 title.as_deref(),
                 should_use_alt_text,
+                options.link_style,
+                ctx.reference_collector.as_ref(),
             )),
             VisitResult::Custom(custom) => Some(custom),
             VisitResult::Skip => None,
@@ -145,6 +147,8 @@ pub fn handle_graphic(
             &alt,
             title.as_deref(),
             should_use_alt_text,
+            options.link_style,
+            ctx.reference_collector.as_ref(),
         ))
     };
 
@@ -154,6 +158,8 @@ pub fn handle_graphic(
         &alt,
         title.as_deref(),
         should_use_alt_text,
+        options.link_style,
+        ctx.reference_collector.as_ref(),
     ));
 
     if !options.skip_images {
@@ -189,21 +195,39 @@ pub fn handle_graphic(
 ///
 /// If `use_alt_only` is true, returns just the alt text.
 /// Otherwise returns the full `![alt](src "title")` syntax.
-fn format_graphic_markdown(src: &str, alt: &str, title: Option<&str>, use_alt_only: bool) -> String {
+fn format_graphic_markdown(
+    src: &str,
+    alt: &str,
+    title: Option<&str>,
+    use_alt_only: bool,
+    link_style: crate::options::validation::LinkStyle,
+    reference_collector: Option<&crate::converter::reference_collector::ReferenceCollectorHandle>,
+) -> String {
     if use_alt_only {
-        alt.to_string()
-    } else {
-        let mut buf = String::with_capacity(src.len() + alt.len() + 10);
-        buf.push_str("![");
-        buf.push_str(alt);
-        buf.push_str("](");
-        buf.push_str(src);
-        if let Some(title_text) = title {
-            buf.push_str(" \"");
-            buf.push_str(title_text);
-            buf.push('"');
+        return alt.to_string();
+    }
+    if link_style == crate::options::validation::LinkStyle::Reference {
+        if let Some(collector) = reference_collector {
+            let ref_num = collector.borrow_mut().get_or_insert(src, title);
+            let mut buf = String::with_capacity(alt.len() + 10);
+            buf.push_str("![");
+            buf.push_str(alt);
+            buf.push_str("][");
+            buf.push_str(&ref_num.to_string());
+            buf.push(']');
+            return buf;
         }
-        buf.push(')');
-        buf
     }
+    let mut buf = String::with_capacity(src.len() + alt.len() + 10);
+    buf.push_str("![");
+    buf.push_str(alt);
+    buf.push_str("](");
+    buf.push_str(src);
+    if let Some(title_text) = title {
+        buf.push_str(" \"");
+        buf.push_str(title_text);
+        buf.push('"');
+    }
+    buf.push(')');
+    buf
 }

data/vendor/html-to-markdown-rs/src/converter/handlers/image.rs

@@ -146,7 +146,14 @@ pub fn handle_img(
             visitor.visit_image(&node_ctx, &src, &alt, title.as_deref())
         };
         match visit_result {
-            VisitResult::Continue => Some(format_image_markdown(&src, &alt, title.as_deref(), should_use_alt_text)),
+            VisitResult::Continue => Some(format_image_markdown(
+                &src,
+                &alt,
+                title.as_deref(),
+                should_use_alt_text,
+                options.link_style,
+                ctx.reference_collector.as_ref(),
+            )),
             VisitResult::Custom(custom) => Some(custom),
             VisitResult::Skip => None,
             VisitResult::Error(err) => {
@@ -158,11 +165,25 @@ pub fn handle_img(
             VisitResult::PreserveHtml => Some(serialize_node(node_handle, parser)),
         }
     } else {
-        Some(format_image_markdown(&src, &alt, title.as_deref(), should_use_alt_text))
+        Some(format_image_markdown(
+            &src,
+            &alt,
+            title.as_deref(),
+            should_use_alt_text,
+            options.link_style,
+            ctx.reference_collector.as_ref(),
+        ))
     };
 
     #[cfg(not(feature = "visitor"))]
-    let image_output = Some(format_image_markdown(&src, &alt, title.as_deref(), should_use_alt_text));
+    let image_output = Some(format_image_markdown(
+        &src,
+        &alt,
+        title.as_deref(),
+        should_use_alt_text,
+        options.link_style,
+        ctx.reference_collector.as_ref(),
+    ));
 
     // Only output image if skip_images is not enabled
     if !options.skip_images {
@@ -192,27 +213,51 @@ pub fn handle_img(
             }
         }
     }
+
+    if let Some(ref sc) = ctx.structure_collector {
+        let src_opt = if src.is_empty() { None } else { Some(src.as_ref()) };
+        let alt_opt = if alt.is_empty() { None } else { Some(alt.as_ref()) };
+        sc.borrow_mut().push_image(src_opt, alt_opt);
+    }
 }
 
 /// Format an image as Markdown syntax.
 ///
 /// If `use_alt_only` is true, returns just the alt text.
 /// Otherwise returns the full `![alt](src "title")` syntax.
-fn format_image_markdown(src: &str, alt: &str, title: Option<&str>, use_alt_only: bool) -> String {
+fn format_image_markdown(
+    src: &str,
+    alt: &str,
+    title: Option<&str>,
+    use_alt_only: bool,
+    link_style: crate::options::validation::LinkStyle,
+    reference_collector: Option<&crate::converter::reference_collector::ReferenceCollectorHandle>,
+) -> String {
     if use_alt_only {
-        alt.to_string()
-    } else {
-        let mut buf = String::with_capacity(src.len() + alt.len() + 10);
-        buf.push_str("![");
-        buf.push_str(alt);
-        buf.push_str("](");
-        buf.push_str(src);
-        if let Some(title_text) = title {
-            buf.push_str(" \"");
-            buf.push_str(title_text);
-            buf.push('"');
+        return alt.to_string();
+    }
+    if link_style == crate::options::validation::LinkStyle::Reference {
+        if let Some(collector) = reference_collector {
+            let ref_num = collector.borrow_mut().get_or_insert(src, title);
+            let mut buf = String::with_capacity(alt.len() + 10);
+            buf.push_str("![");
+            buf.push_str(alt);
+            buf.push_str("][");
+            buf.push_str(&ref_num.to_string());
+            buf.push(']');
+            return buf;
         }
-        buf.push(')');
-        buf
     }
+    let mut buf = String::with_capacity(src.len() + alt.len() + 10);
+    buf.push_str("![");
+    buf.push_str(alt);
+    buf.push_str("](");
+    buf.push_str(src);
+    if let Some(title_text) = title {
+        buf.push_str(" \"");
+        buf.push_str(title_text);
+        buf.push('"');
+    }
+    buf.push(')');
+    buf
 }

data/vendor/html-to-markdown-rs/src/converter/handlers/link.rs

@@ -115,6 +115,7 @@ pub fn handle_link(
                             title.as_deref(),
                             raw_text.as_str(),
                             options,
+                            ctx.reference_collector.as_ref(),
                         );
                         push_heading(output, ctx, options, heading_level, link_buffer.as_str());
                         return;
@@ -190,6 +191,13 @@ pub fn handle_link(
             label = href.clone();
         }
 
+        // Normalize Wikipedia-style back-reference links: <a href="#cite_ref-N">^</a>
+        // These produce `[^](#cite_ref-N)` which is confusing (looks like a footnote).
+        // Convert to `[↑](#cite_ref-N)` to avoid ambiguity with markdown footnote syntax.
+        if label == "^" && href.starts_with('#') {
+            label = "↑".to_string();
+        }
+
         let escaped_label = escape_link_label(&label);
 
         #[cfg(feature = "visitor")]
@@ -226,6 +234,7 @@ pub fn handle_link(
                         title.as_deref(),
                         label.as_str(),
                         options,
+                        ctx.reference_collector.as_ref(),
                     );
                     Some(buf)
                 }
@@ -248,6 +257,7 @@ pub fn handle_link(
                 title.as_deref(),
                 label.as_str(),
                 options,
+                ctx.reference_collector.as_ref(),
             );
             Some(buf)
         };
@@ -262,6 +272,7 @@ pub fn handle_link(
                 title.as_deref(),
                 label.as_str(),
                 options,
+                ctx.reference_collector.as_ref(),
             );
             Some(buf)
         };

data/vendor/html-to-markdown-rs/src/converter/inline/link.rs

@@ -145,6 +145,7 @@ pub(crate) fn handle(
                             title.as_deref(),
                             raw_text.as_str(),
                             options,
+                            ctx.reference_collector.as_ref(),
                         );
                         push_heading(output, ctx, options, heading_level, link_buffer.as_str());
                         return;
@@ -262,6 +263,7 @@ pub(crate) fn handle(
                         title.as_deref(),
                         label.as_str(),
                         options,
+                        ctx.reference_collector.as_ref(),
                     );
                     Some(buf)
                 }
@@ -284,6 +286,7 @@ pub(crate) fn handle(
                 title.as_deref(),
                 label.as_str(),
                 options,
+                ctx.reference_collector.as_ref(),
             );
             Some(buf)
         };
@@ -298,6 +301,7 @@ pub(crate) fn handle(
                 title.as_deref(),
                 label.as_str(),
                 options,
+                ctx.reference_collector.as_ref(),
             );
             Some(buf)
         };
@@ -363,7 +367,20 @@ pub(crate) fn append_markdown_link(
     title: Option<&str>,
     raw_text: &str,
     options: &ConversionOptions,
+    reference_collector: Option<&crate::converter::reference_collector::ReferenceCollectorHandle>,
 ) {
+    if options.link_style == crate::options::validation::LinkStyle::Reference && !href.is_empty() {
+        if let Some(collector) = reference_collector {
+            let ref_num = collector.borrow_mut().get_or_insert(href, title);
+            output.push('[');
+            output.push_str(label);
+            output.push_str("][");
+            output.push_str(&ref_num.to_string());
+            output.push(']');
+            return;
+        }
+    }
+
     output.push('[');
     output.push_str(label);
     output.push_str("](");

data/vendor/html-to-markdown-rs/src/converter/list/item.rs

@@ -204,6 +204,8 @@ pub(crate) fn handle_li(
             }
         }
 
+        let item_start_pos = output.len();
+
         let children = tag.children();
         {
             for child_handle in children.top().iter() {
@@ -213,6 +215,18 @@ pub(crate) fn handle_li(
 
         trim_trailing_whitespace(output);
 
+        if !ctx.in_table_cell {
+            if let Some(ref sc) = ctx.structure_collector {
+                if item_start_pos <= output.len() && output.is_char_boundary(item_start_pos) {
+                    let rendered = &output[item_start_pos..];
+                    let content = rendered.trim();
+                    if !content.is_empty() {
+                        sc.borrow_mut().push_list_item(content);
+                    }
+                }
+            }
+        }
+
         #[cfg(feature = "visitor")]
         if let Some(ref visitor_handle) = ctx.visitor {
             use crate::visitor::{NodeContext, NodeType, VisitResult};

data/vendor/html-to-markdown-rs/src/converter/list/ordered.rs

@@ -107,6 +107,12 @@ pub(crate) fn handle_ol(
         }
     }
 
+    if !ctx.in_table_cell {
+        if let Some(ref sc) = ctx.structure_collector {
+            sc.borrow_mut().push_list_start(true);
+        }
+    }
+
     process_list_children(
         *node_handle,
         parser,
@@ -121,6 +127,12 @@ pub(crate) fn handle_ol(
         dom_ctx,
     );
 
+    if !ctx.in_table_cell {
+        if let Some(ref sc) = ctx.structure_collector {
+            sc.borrow_mut().push_list_end();
+        }
+    }
+
     add_nested_list_trailing_separator(output, ctx);
 
     #[cfg(feature = "visitor")]

data/vendor/html-to-markdown-rs/src/converter/list/unordered.rs

@@ -101,6 +101,12 @@ pub(crate) fn handle_ul(
         }
     }
 
+    if !ctx.in_table_cell {
+        if let Some(ref sc) = ctx.structure_collector {
+            sc.borrow_mut().push_list_start(false);
+        }
+    }
+
     process_list_children(
         *node_handle,
         parser,
@@ -115,6 +121,12 @@ pub(crate) fn handle_ul(
         dom_ctx,
     );
 
+    if !ctx.in_table_cell {
+        if let Some(ref sc) = ctx.structure_collector {
+            sc.borrow_mut().push_list_end();
+        }
+    }
+
     add_nested_list_trailing_separator(output, ctx);
 
     #[cfg(feature = "visitor")]

data/vendor/html-to-markdown-rs/src/converter/main.rs

@@ -196,6 +196,14 @@ pub(crate) fn convert_html_impl(
         }
     }
 
+    let reference_collector = if options.link_style == crate::options::LinkStyle::Reference {
+        Some(std::rc::Rc::new(std::cell::RefCell::new(
+            crate::converter::reference_collector::ReferenceCollector::new(),
+        )))
+    } else {
+        None
+    };
+
     #[cfg(all(feature = "metadata", feature = "visitor"))]
     let ctx = Context::new(
         options,
@@ -203,6 +211,7 @@ pub(crate) fn convert_html_impl(
         metadata_collector,
         visitor,
         structure_collector.as_ref().map(std::rc::Rc::clone),
+        reference_collector.as_ref().map(std::rc::Rc::clone),
     );
     #[cfg(all(feature = "metadata", not(feature = "visitor")))]
     let ctx = Context::new(
@@ -211,6 +220,7 @@ pub(crate) fn convert_html_impl(
         metadata_collector,
         _visitor,
         structure_collector.as_ref().map(std::rc::Rc::clone),
+        reference_collector.as_ref().map(std::rc::Rc::clone),
     );
     #[cfg(all(not(feature = "metadata"), feature = "visitor"))]
     let ctx = Context::new(
@@ -219,6 +229,7 @@ pub(crate) fn convert_html_impl(
         _metadata_collector,
         visitor,
         structure_collector.as_ref().map(std::rc::Rc::clone),
+        reference_collector.as_ref().map(std::rc::Rc::clone),
     );
     #[cfg(all(not(feature = "metadata"), not(feature = "visitor")))]
     let ctx = Context::new(
@@ -227,6 +238,7 @@ pub(crate) fn convert_html_impl(
         _metadata_collector,
         _visitor,
         structure_collector.as_ref().map(std::rc::Rc::clone),
+        reference_collector.as_ref().map(std::rc::Rc::clone),
     );
 
     for child_handle in dom.children() {
@@ -242,6 +254,19 @@ pub(crate) fn convert_html_impl(
     // reference to the same collector, and Rc::try_unwrap requires exactly one reference.
     drop(ctx);
 
+    // Append reference-style link definitions if any were collected
+    if let Some(rc) = reference_collector {
+        if let Ok(collector) = std::rc::Rc::try_unwrap(rc) {
+            let ref_section = collector.into_inner().finish();
+            if !ref_section.is_empty() {
+                let trimmed_len = output.trim_end_matches('\n').len();
+                output.truncate(trimmed_len);
+                output.push_str("\n\n");
+                output.push_str(&ref_section);
+            }
+        }
+    }
+
     // If plain text was requested, discard the markdown output and return plain text.
     // The full pipeline was still run above so that metadata + visitor callbacks fire.
     if is_plain_text {

data/vendor/html-to-markdown-rs/src/converter/media/embedded.rs

@@ -78,11 +78,20 @@ pub(crate) fn handle_audio(
     };
 
     if should_output_media_link(&src) {
-        output.push('[');
-        output.push_str(&src);
-        output.push_str("](");
-        output.push_str(&src);
-        output.push(')');
+        if let Some(ref collector) = ctx.reference_collector {
+            let ref_num = collector.borrow_mut().get_or_insert(&src, None);
+            output.push('[');
+            output.push_str(&src);
+            output.push_str("][");
+            output.push_str(&ref_num.to_string());
+            output.push(']');
+        } else {
+            output.push('[');
+            output.push_str(&src);
+            output.push_str("](");
+            output.push_str(&src);
+            output.push(')');
+        }
         if !ctx.in_paragraph && !ctx.convert_as_inline {
             output.push_str("\n\n");
         }
@@ -132,11 +141,20 @@ pub(crate) fn handle_video(
     };
 
     if should_output_media_link(&src) {
-        output.push('[');
-        output.push_str(&src);
-        output.push_str("](");
-        output.push_str(&src);
-        output.push(')');
+        if let Some(ref collector) = ctx.reference_collector {
+            let ref_num = collector.borrow_mut().get_or_insert(&src, None);
+            output.push('[');
+            output.push_str(&src);
+            output.push_str("][");
+            output.push_str(&ref_num.to_string());
+            output.push(']');
+        } else {
+            output.push('[');
+            output.push_str(&src);
+            output.push_str("](");
+            output.push_str(&src);
+            output.push(')');
+        }
         if !ctx.in_paragraph && !ctx.convert_as_inline {
             output.push_str("\n\n");
         }
@@ -199,11 +217,20 @@ pub(crate) fn handle_iframe(tag: &HTMLTag, output: &mut String, ctx: &Context) {
         .map_or(Cow::Borrowed(""), |v| v.as_utf8_str());
 
     if !src.is_empty() {
-        output.push('[');
-        output.push_str(&src);
-        output.push_str("](");
-        output.push_str(&src);
-        output.push(')');
+        if let Some(ref collector) = ctx.reference_collector {
+            let ref_num = collector.borrow_mut().get_or_insert(&src, None);
+            output.push('[');
+            output.push_str(&src);
+            output.push_str("][");
+            output.push_str(&ref_num.to_string());
+            output.push(']');
+        } else {
+            output.push('[');
+            output.push_str(&src);
+            output.push_str("](");
+            output.push_str(&src);
+            output.push(')');
+        }
         if !ctx.in_paragraph && !ctx.convert_as_inline {
             output.push_str("\n\n");
         }

data/vendor/html-to-markdown-rs/src/converter/mod.rs

@@ -103,6 +103,7 @@ pub mod media;
 mod metadata;
 pub mod plain_text;
 pub mod preprocessing_helpers;
+pub mod reference_collector;
 pub mod semantic;
 pub mod text;
 mod text_node;

data/vendor/html-to-markdown-rs/src/converter/reference_collector.rs

@@ -0,0 +1,69 @@
+//! Collector for reference-style link definitions.
+
+use std::cell::RefCell;
+use std::collections::HashMap;
+use std::rc::Rc;
+
+/// Shared handle for passing the collector through the conversion context.
+pub type ReferenceCollectorHandle = Rc<RefCell<ReferenceCollector>>;
+
+#[derive(Debug, Clone, Hash, Eq, PartialEq)]
+struct ReferenceKey {
+    url: String,
+    title: Option<String>,
+}
+
+/// Collects link/image references during conversion and produces a reference
+/// definitions section at the end of the document.
+#[derive(Debug, Default)]
+pub struct ReferenceCollector {
+    map: HashMap<ReferenceKey, usize>,
+    entries: Vec<(usize, String, Option<String>)>,
+}
+
+impl ReferenceCollector {
+    /// Create a new, empty reference collector.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Register a URL (and optional title) and return its 1-based reference number.
+    ///
+    /// If the same URL+title pair was already registered, the existing number is returned.
+    pub fn get_or_insert(&mut self, url: &str, title: Option<&str>) -> usize {
+        let key = ReferenceKey {
+            url: url.to_string(),
+            title: title.map(String::from),
+        };
+        if let Some(&num) = self.map.get(&key) {
+            return num;
+        }
+        let num = self.entries.len() + 1;
+        self.map.insert(key, num);
+        self.entries.push((num, url.to_string(), title.map(String::from)));
+        num
+    }
+
+    /// Produce the reference definitions section.
+    ///
+    /// Returns an empty string when no references were collected.
+    pub fn finish(&self) -> String {
+        if self.entries.is_empty() {
+            return String::new();
+        }
+        let mut out = String::new();
+        for (num, url, title) in &self.entries {
+            out.push('[');
+            out.push_str(&num.to_string());
+            out.push_str("]: ");
+            out.push_str(url);
+            if let Some(t) = title {
+                out.push_str(" \"");
+                out.push_str(&t.replace('"', "\\\""));
+                out.push('"');
+            }
+            out.push('\n');
+        }
+        out
+    }
+}

data/vendor/html-to-markdown-rs/src/exports.rs

@@ -18,6 +18,7 @@ pub use crate::metadata::{
 };
 
 pub use crate::options::{
-    CodeBlockStyle, ConversionOptions, ConversionOptionsUpdate, HeadingStyle, HighlightStyle, ListIndentType,
-    NewlineStyle, OutputFormat, PreprocessingOptions, PreprocessingOptionsUpdate, PreprocessingPreset, WhitespaceMode,
+    CodeBlockStyle, ConversionOptions, ConversionOptionsUpdate, HeadingStyle, HighlightStyle, LinkStyle,
+    ListIndentType, NewlineStyle, OutputFormat, PreprocessingOptions, PreprocessingOptionsUpdate, PreprocessingPreset,
+    WhitespaceMode,
 };

data/vendor/html-to-markdown-rs/src/options/conversion.rs

@@ -4,7 +4,7 @@
 
 use crate::options::preprocessing::PreprocessingOptions;
 use crate::options::validation::{
-    CodeBlockStyle, HeadingStyle, HighlightStyle, ListIndentType, NewlineStyle, OutputFormat, WhitespaceMode,
+    CodeBlockStyle, HeadingStyle, HighlightStyle, LinkStyle, ListIndentType, NewlineStyle, OutputFormat, WhitespaceMode,
 };
 
 /// Main conversion options for HTML to Markdown conversion.
@@ -94,6 +94,8 @@ pub struct ConversionOptions {
     pub preserve_tags: Vec<String>,
     /// Skip conversion of `<img>` elements (omit images from output).
     pub skip_images: bool,
+    /// Link rendering style (inline or reference).
+    pub link_style: LinkStyle,
     /// Target output format (Markdown, plain text, etc.).
     pub output_format: OutputFormat,
     /// Include structured document tree in result.
@@ -142,6 +144,7 @@ impl Default for ConversionOptions {
             strip_tags: Vec::new(),
             preserve_tags: Vec::new(),
             skip_images: false,
+            link_style: LinkStyle::default(),
             output_format: OutputFormat::default(),
             include_document_structure: false,
             extract_images: false,
@@ -207,6 +210,7 @@ impl ConversionOptionsBuilder {
     builder_setter!(newline_style, NewlineStyle);
     builder_setter!(highlight_style, HighlightStyle);
     builder_setter_into!(code_language, String);
+    builder_setter!(link_style, LinkStyle);
     builder_setter!(autolinks, bool);
     builder_setter!(default_title, bool);
     builder_setter!(br_in_tables, bool);
@@ -356,6 +360,8 @@ pub struct ConversionOptionsUpdate {
     pub preserve_tags: Option<Vec<String>>,
     /// Optional override for [`ConversionOptions::skip_images`].
     pub skip_images: Option<bool>,
+    /// Optional override for [`ConversionOptions::link_style`].
+    pub link_style: Option<LinkStyle>,
     /// Optional override for [`ConversionOptions::output_format`].
     pub output_format: Option<OutputFormat>,
     /// Optional override for [`ConversionOptions::include_document_structure`].
@@ -410,6 +416,7 @@ impl ConversionOptions {
         apply!(strip_tags);
         apply!(preserve_tags);
         apply!(skip_images);
+        apply!(link_style);
         apply!(output_format);
         apply!(include_document_structure);
         apply!(extract_images);

data/vendor/html-to-markdown-rs/src/options/mod.rs

@@ -13,7 +13,7 @@ pub mod validation;
 pub use conversion::{ConversionOptions, ConversionOptionsUpdate};
 pub use preprocessing::{PreprocessingOptions, PreprocessingOptionsUpdate, PreprocessingPreset};
 pub use validation::{
-    CodeBlockStyle, HeadingStyle, HighlightStyle, ListIndentType, NewlineStyle, OutputFormat, WhitespaceMode,
+    CodeBlockStyle, HeadingStyle, HighlightStyle, LinkStyle, ListIndentType, NewlineStyle, OutputFormat, WhitespaceMode,
 };
 
 // Note: InlineImageConfig is re-exported from the inline_images module,

data/vendor/html-to-markdown-rs/src/options/validation.rs

@@ -172,6 +172,33 @@ impl HighlightStyle {
     }
 }
 
+/// Link rendering style in Markdown output.
+///
+/// Controls whether links and images use inline `[text](url)` syntax or
+/// reference-style `[text][1]` syntax with definitions collected at the end.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum LinkStyle {
+    /// Inline links: `[text](url)`. Default.
+    #[default]
+    Inline,
+    /// Reference-style links: `[text][1]` with `[1]: url` at end of document.
+    Reference,
+}
+
+impl LinkStyle {
+    /// Parse a link style from a string.
+    ///
+    /// Accepts "reference" or defaults to Inline.
+    /// Input is normalized (lowercased, alphanumeric only).
+    #[must_use]
+    pub fn parse(value: &str) -> Self {
+        match normalize_token(value).as_str() {
+            "reference" => Self::Reference,
+            _ => Self::Inline,
+        }
+    }
+}
+
 /// Output format for conversion.
 ///
 /// Specifies the target markup language format for the conversion output.
@@ -215,7 +242,8 @@ pub(crate) fn normalize_token(value: &str) -> String {
 #[cfg(any(feature = "serde", feature = "metadata"))]
 mod serde_impls {
     use super::{
-        CodeBlockStyle, HeadingStyle, HighlightStyle, ListIndentType, NewlineStyle, OutputFormat, WhitespaceMode,
+        CodeBlockStyle, HeadingStyle, HighlightStyle, LinkStyle, ListIndentType, NewlineStyle, OutputFormat,
+        WhitespaceMode,
     };
     use serde::{Deserialize, Serialize, Serializer};
 
@@ -239,6 +267,7 @@ mod serde_impls {
     impl_deserialize_from_parse!(NewlineStyle, NewlineStyle::parse);
     impl_deserialize_from_parse!(CodeBlockStyle, CodeBlockStyle::parse);
     impl_deserialize_from_parse!(HighlightStyle, HighlightStyle::parse);
+    impl_deserialize_from_parse!(LinkStyle, LinkStyle::parse);
     impl_deserialize_from_parse!(OutputFormat, OutputFormat::parse);
 
     // Serialize implementations that convert enum variants to their string representations
@@ -324,6 +353,19 @@ mod serde_impls {
         }
     }
 
+    impl Serialize for LinkStyle {
+        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+        where
+            S: Serializer,
+        {
+            let s = match self {
+                Self::Inline => "inline",
+                Self::Reference => "reference",
+            };
+            serializer.serialize_str(s)
+        }
+    }
+
     impl Serialize for OutputFormat {
         fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
         where

data/vendor/html-to-markdown-rs/src/types/structure_builder.rs

@@ -226,7 +226,8 @@ fn make_node_id(node_type: &str, text: &str, index: usize) -> String {
     let mut hasher = DefaultHasher::new();
     node_type.hash(&mut hasher);
     // Only hash a prefix of the text to keep cost bounded.
-    text[..text.len().min(64)].hash(&mut hasher);
+    let end = crate::converter::utility::content::floor_char_boundary(text, text.len().min(64));
+    text[..end].hash(&mut hasher);
     index.hash(&mut hasher);
     let digest = hasher.finish();
     format!("{node_type}-{digest:016x}")

data/vendor/html-to-markdown-rs/src/types/structure_collector.rs

@@ -347,7 +347,8 @@ impl StructureCollector {
 
         let mut hasher = DefaultHasher::new();
         node_type.hash(&mut hasher);
-        text[..text.len().min(64)].hash(&mut hasher);
+        let end = crate::converter::utility::content::floor_char_boundary(text, text.len().min(64));
+        text[..end].hash(&mut hasher);
         index.hash(&mut hasher);
         let digest = hasher.finish();
         format!("{node_type}-{digest:016x}")

data/vendor/html-to-markdown-rs/tests/integration_test.rs

@@ -591,6 +591,30 @@ fn q_element_produces_quotes() {
     assert!(result.contains(r#""hello""#), "q element should add quotes: {result}");
 }
 
+#[test]
+fn test_wikipedia_back_reference_caret_normalized() {
+    // Wikipedia back-references use <a href="#cite_ref-N">^</a>
+    // The caret should be normalized to ↑ to avoid confusion with markdown footnote syntax
+    let html = r##"<p>Some text<sup><a href="#cite_ref-1">^</a></sup> more text</p>"##;
+    let result = convert(html, None).unwrap();
+    assert!(
+        result.contains("[↑](#cite_ref-1)"),
+        "Back-reference caret should be normalized to ↑: {result}"
+    );
+    assert!(
+        !result.contains("[^]"),
+        "Should not produce [^] which looks like footnote syntax: {result}"
+    );
+}
+
+#[test]
+fn test_regular_caret_link_not_affected() {
+    // Regular links with ^ text but no # href should keep the ^
+    let html = r#"<a href="https://example.com">^</a>"#;
+    let result = convert(html, None).unwrap();
+    assert!(result.contains("[^]"), "Non-anchor caret links should keep ^: {result}");
+}
+
 fn convert(
     html: &str,
     opts: Option<html_to_markdown_rs::ConversionOptions>,

data/vendor/html-to-markdown-rs/tests/reference_links_test.rs

@@ -0,0 +1,169 @@
+#![allow(missing_docs)]
+
+use html_to_markdown_rs::{ConversionOptions, LinkStyle};
+
+fn convert(html: &str, options: Option<ConversionOptions>) -> String {
+    html_to_markdown_rs::convert(html, options)
+        .unwrap()
+        .content
+        .unwrap_or_default()
+}
+
+fn ref_options() -> ConversionOptions {
+    ConversionOptions {
+        link_style: LinkStyle::Reference,
+        ..Default::default()
+    }
+}
+
+#[test]
+fn basic_reference_link() {
+    let html = r#"<a href="https://example.com">Click here</a>"#;
+    let result = convert(html, Some(ref_options()));
+    assert!(
+        result.contains("[Click here][1]"),
+        "Expected reference-style link, got: {result}"
+    );
+    assert!(
+        result.contains("[1]: https://example.com"),
+        "Expected reference definition, got: {result}"
+    );
+}
+
+#[test]
+fn reference_link_with_title() {
+    let html = r#"<a href="https://example.com" title="Example">Click</a>"#;
+    let result = convert(html, Some(ref_options()));
+    assert!(
+        result.contains("[Click][1]"),
+        "Expected reference-style link, got: {result}"
+    );
+    assert!(
+        result.contains(r#"[1]: https://example.com "Example""#),
+        "Expected reference definition with title, got: {result}"
+    );
+}
+
+#[test]
+fn url_deduplication() {
+    let html = r#"<a href="https://example.com">First</a> <a href="https://example.com">Second</a>"#;
+    let result = convert(html, Some(ref_options()));
+    assert!(
+        result.contains("[First][1]"),
+        "Expected first link with ref 1, got: {result}"
+    );
+    assert!(
+        result.contains("[Second][1]"),
+        "Expected second link reusing ref 1, got: {result}"
+    );
+    // Should only have one definition
+    let count = result.matches("[1]: https://example.com").count();
+    assert_eq!(count, 1, "Expected exactly one definition, got: {result}");
+}
+
+#[test]
+fn different_titles_different_refs() {
+    let html =
+        r#"<a href="https://example.com" title="A">First</a> <a href="https://example.com" title="B">Second</a>"#;
+    let result = convert(html, Some(ref_options()));
+    assert!(
+        result.contains("[First][1]"),
+        "Expected first link ref 1, got: {result}"
+    );
+    assert!(
+        result.contains("[Second][2]"),
+        "Expected second link ref 2 (different title), got: {result}"
+    );
+}
+
+#[test]
+fn image_reference_style() {
+    let html = r#"<img src="https://example.com/img.png" alt="A photo">"#;
+    let result = convert(html, Some(ref_options()));
+    assert!(
+        result.contains("![A photo][1]"),
+        "Expected reference-style image, got: {result}"
+    );
+    assert!(
+        result.contains("[1]: https://example.com/img.png"),
+        "Expected image reference definition, got: {result}"
+    );
+}
+
+#[test]
+fn mixed_links_and_images_share_numbering() {
+    let html = r#"<a href="https://a.com">Link</a><img src="https://b.com/img.png" alt="Img">"#;
+    let result = convert(html, Some(ref_options()));
+    assert!(result.contains("[Link][1]"), "Expected link as ref 1, got: {result}");
+    assert!(result.contains("![Img][2]"), "Expected image as ref 2, got: {result}");
+}
+
+#[test]
+fn autolinks_unaffected() {
+    let html = r#"<a href="https://example.com">https://example.com</a>"#;
+    let options = ConversionOptions {
+        link_style: LinkStyle::Reference,
+        autolinks: true,
+        ..Default::default()
+    };
+    let result = convert(html, Some(options));
+    // Autolinks should still render as <url>
+    assert!(
+        result.contains("<https://example.com>"),
+        "Autolinks should not be affected by reference style, got: {result}"
+    );
+}
+
+#[test]
+fn default_inline_unchanged() {
+    let html = r#"<a href="https://example.com">Click</a>"#;
+    let result = convert(html, None);
+    assert!(
+        result.contains("[Click](https://example.com)"),
+        "Default should use inline style, got: {result}"
+    );
+}
+
+#[test]
+fn multiple_paragraphs_references_at_end() {
+    let html = r#"<p><a href="https://a.com">A</a></p><p><a href="https://b.com">B</a></p>"#;
+    let result = convert(html, Some(ref_options()));
+    // References should be at the very end
+    let ref_section_start = result.find("[1]:").expect("Should have ref section");
+    let content_end = result.find("[A][1]").expect("Should have inline ref");
+    assert!(
+        ref_section_start > content_end,
+        "Reference section should be after content"
+    );
+}
+
+#[test]
+fn empty_href_no_reference() {
+    let html = r#"<a href="">Empty</a>"#;
+    let result = convert(html, Some(ref_options()));
+    // Empty href should not create a reference
+    assert!(
+        !result.contains("[1]:"),
+        "Empty href should not create reference, got: {result}"
+    );
+}
+
+#[test]
+fn title_with_quotes_escaped() {
+    let html = r#"<a href="https://example.com" title='Say "hello"'>Link</a>"#;
+    let result = convert(html, Some(ref_options()));
+    assert!(
+        result.contains(r#"[1]: https://example.com "Say \"hello\"""#),
+        "Quotes in title should be escaped, got: {result}"
+    );
+}
+
+#[test]
+fn media_elements_reference_style() {
+    let html = r#"<video src="https://example.com/video.mp4"></video>"#;
+    let result = convert(html, Some(ref_options()));
+    assert!(
+        result.contains("[1]: https://example.com/video.mp4"),
+        "Video should use reference style, got: {result}"
+    );
+}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: html-to-markdown
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.1.0
 platform: ruby
 authors:
 - Na'aman Hirschfeld
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -142,6 +142,7 @@ files:
 - vendor/html-to-markdown-rs/src/converter/mod.rs
 - vendor/html-to-markdown-rs/src/converter/plain_text.rs
 - vendor/html-to-markdown-rs/src/converter/preprocessing_helpers.rs
+- vendor/html-to-markdown-rs/src/converter/reference_collector.rs
 - vendor/html-to-markdown-rs/src/converter/semantic/attributes.rs
 - vendor/html-to-markdown-rs/src/converter/semantic/definition_list.rs
 - vendor/html-to-markdown-rs/src/converter/semantic/figure.rs
@@ -224,6 +225,7 @@ files:
 - vendor/html-to-markdown-rs/tests/lists_test.rs
 - vendor/html-to-markdown-rs/tests/plain_output_test.rs
 - vendor/html-to-markdown-rs/tests/preprocessing_tests.rs
+- vendor/html-to-markdown-rs/tests/reference_links_test.rs
 - vendor/html-to-markdown-rs/tests/skip_images_test.rs
 - vendor/html-to-markdown-rs/tests/tables_test.rs
 - vendor/html-to-markdown-rs/tests/test_custom_elements.rs