html-to-markdown 3.0.2 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2761dc167e2c7f7e0e27da4367660d7dc4d18f853b5b5add976019434a37de0
-  data.tar.gz: 8d6822eb08fc782524c4ec35446c48ff017bd2aa640f2515e79c05e4d89508b7
+  metadata.gz: c23b51454716c4f5224bc9a0b6cfcfcf3f9935709379395662d9d89cab96f223
+  data.tar.gz: '0878f8bad06ca970013d87f6064150bed2db8b5e12d087474acaa4dd17a00559'
 SHA512:
-  metadata.gz: 93b26fafdae4c4beca9fc6134a3ba2948369210900c8145e1ad72b1714db86e453523361e39308b8d78d5b94d8dc83e33259c2ae2eca727c1b20f3c1629b81c7
-  data.tar.gz: 69d16a9ff3a3d67a3cd267d9c0ff7ed48b9f3736e01fa87f5ec7ae2dd1b79263dea40d9e54392ab50546d12ccfd0c9486b3a728e45344009769a1f1fd2a65bd2
+  metadata.gz: e21bd6d2ec9cbd40df454f2b441cb2da333b1c73a062686f830c4bd3368dad2dacec3bb0953f5c8902ad2ab411453c690597d64f0c86103d65b71438c647a7f1
+  data.tar.gz: 38cf61f5035e6becae227f4117f10208eb9b0ca2d99b805b6e8feefdc8bf2611e44605c967218ea69892df3af8a417026fb70e20cb3ab9a9e28771c3ecc723c9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    html-to-markdown (3.0.2)
+    html-to-markdown (3.1.0)
       rb_sys (>= 0.9, < 1.0)
 
 GEM
@@ -153,7 +153,7 @@ CHECKSUMS
   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.2)
+  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

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.2" 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.toml

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

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/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 {
@@ -204,21 +225,39 @@ pub fn handle_img(
 ///
 /// 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/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/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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: html-to-markdown
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.1.0
 platform: ruby
 authors:
 - Na'aman Hirschfeld
@@ -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