html-to-markdown 2.27.3 → 2.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c1f001483774ae8b601ba6953cf5e42a798840cc2d99f1048f54977cde509cf
-  data.tar.gz: 1d3953f85ef0cd47ba65ee7f83f15f7233a31b8e8dd1c370024d85f893539eda
+  metadata.gz: ee40f54b9f0a1b031a8a4c6a75caac7797e452dfb2fa076d79a6b69fdcd6093d
+  data.tar.gz: dd1fbfbcc08e4a562a4c096c7530104104054eb3546acbb8fbf265941ab381a7
 SHA512:
-  metadata.gz: 95258f98b61c5029f06e8c91f7f78e37fa74275038b6846ade5cbf7a5d16bced41336ec4f5eb7ddf6c110c41a30a2461eb6f293c19adde5c0c038f0bf67a272f
-  data.tar.gz: 6dae1754667432115bbc7a18b3eb92f95a20bc1e8fc1de24672d23a63fb7f59d80beef17204a60eb2ab2a1d886232b031a141ba827f925bbbbbac77d6cc97e3c
+  metadata.gz: 7bef90afd805e6d0333d76fbec1c2698b62ca2f3260c4d5566d638d3950d606e2fd6b1f85c02f2c40fa39279929951ba8e8e666fde9e09ad6d0e2753c2d730e7
+  data.tar.gz: adf885b78edf97063b30e9285f2f33d3e1cee2a657e282e50d6f548fe13b686b0e3c4f4008248482d78f686ddf0041d4e1581ddfcd02bdb37a3bc66fdb88310a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    html-to-markdown (2.27.3)
+    html-to-markdown (2.28.0)
       rb_sys (>= 0.9, < 1.0)
 
 GEM
@@ -172,7 +172,7 @@ CHECKSUMS
   ffi (1.17.3-x86_64-darwin) sha256=1f211811eb5cfaa25998322cdd92ab104bfbd26d1c4c08471599c511f2c00bb5
   ffi (1.17.3-x86_64-linux-gnu) sha256=3746b01f677aae7b16dc1acb7cb3cc17b3e35bdae7676a3f568153fb0e2c887f
   fileutils (1.8.0) sha256=8c6b1df54e2540bdb2f39258f08af78853aa70bad52b4d394bbc6424593c6e02
-  html-to-markdown (2.27.3)
+  html-to-markdown (2.28.0)
   i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
   json (2.18.1) sha256=fe112755501b8d0466b5ada6cf50c8c3f41e897fa128ac5d263ec09eedc9f986
   json-schema (6.1.0) sha256=6bf70a2cfb6dfd5a06da28093fa8190f324c88eabd36a7f47097f227321dc702

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

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

data/ext/html-to-markdown-rb/native/src/conversion/mod.rs

@@ -5,7 +5,13 @@ pub mod inline_images;
 #[cfg(feature = "metadata")]
 pub mod metadata;
 
+#[cfg(feature = "visitor")]
+pub mod tables;
+
 pub use inline_images::*;
 
 #[cfg(feature = "metadata")]
 pub use metadata::*;
+
+#[cfg(feature = "visitor")]
+pub use tables::*;

data/ext/html-to-markdown-rb/native/src/conversion/tables.rs

@@ -0,0 +1,71 @@
+//! Table extraction conversion functions for Ruby bindings.
+
+use html_to_markdown_rs::{ConversionWithTables, TableData};
+use magnus::prelude::*;
+use magnus::{Error, Ruby, Value};
+
+#[cfg(feature = "metadata")]
+use super::metadata::extended_metadata_to_ruby;
+
+fn table_data_to_ruby(ruby: &Ruby, table: TableData) -> Result<Value, Error> {
+    let hash = ruby.hash_new();
+
+    // cells: Array[Array[String]]
+    let cells_array = ruby.ary_new();
+    for row in table.cells {
+        let row_array = ruby.ary_new();
+        for cell in row {
+            row_array.push(cell)?;
+        }
+        cells_array.push(row_array)?;
+    }
+    hash.aset(ruby.intern("cells"), cells_array)?;
+
+    // markdown: String
+    hash.aset(ruby.intern("markdown"), table.markdown)?;
+
+    // is_header_row: Array[bool]
+    let header_array = ruby.ary_new();
+    for is_header in table.is_header_row {
+        header_array.push(is_header)?;
+    }
+    hash.aset(ruby.intern("is_header_row"), header_array)?;
+
+    Ok(hash.as_value())
+}
+
+/// Convert a `ConversionWithTables` result to a Ruby Hash.
+///
+/// Returns a Hash with keys `:content`, `:metadata`, `:tables`.
+pub fn tables_result_to_ruby(ruby: &Ruby, result: ConversionWithTables) -> Result<Value, Error> {
+    let hash = ruby.hash_new();
+
+    // content: String
+    hash.aset(ruby.intern("content"), result.content)?;
+
+    // metadata: Hash or nil
+    #[cfg(feature = "metadata")]
+    {
+        match result.metadata {
+            Some(metadata) => {
+                hash.aset(ruby.intern("metadata"), extended_metadata_to_ruby(ruby, metadata)?)?;
+            }
+            None => {
+                hash.aset(ruby.intern("metadata"), ruby.qnil())?;
+            }
+        }
+    }
+    #[cfg(not(feature = "metadata"))]
+    {
+        hash.aset(ruby.intern("metadata"), ruby.qnil())?;
+    }
+
+    // tables: Array[Hash]
+    let tables_array = ruby.ary_new();
+    for table in result.tables {
+        tables_array.push(table_data_to_ruby(ruby, table)?)?;
+    }
+    hash.aset(ruby.intern("tables"), tables_array)?;
+
+    Ok(hash.as_value())
+}

data/ext/html-to-markdown-rb/native/src/lib.rs

@@ -8,6 +8,9 @@ use html_to_markdown_rs::{
 #[cfg(feature = "visitor")]
 use html_to_markdown_rs::convert_with_visitor as convert_with_visitor_inner;
 
+#[cfg(feature = "visitor")]
+use html_to_markdown_rs::convert_with_tables as convert_with_tables_inner;
+
 #[cfg(feature = "metadata")]
 use html_to_markdown_rs::convert_with_metadata as convert_with_metadata_inner;
 
@@ -26,6 +29,9 @@ use types::{arg_error, runtime_error};
 #[cfg(feature = "metadata")]
 use conversion::{build_metadata_config, extended_metadata_to_ruby};
 
+#[cfg(feature = "visitor")]
+use conversion::tables_result_to_ruby;
+
 #[cfg(feature = "visitor")]
 use visitor::RubyVisitorWrapper;
 
@@ -138,6 +144,23 @@ fn convert_with_metadata_handle_fn(ruby: &Ruby, args: &[Value]) -> Result<Value,
     Ok(array.as_value())
 }
 
+#[cfg(feature = "visitor")]
+fn convert_with_tables_fn(ruby: &Ruby, args: &[Value]) -> Result<Value, Error> {
+    let parsed = scan_args::<(String,), (Option<Value>, Option<Value>), (), (), (), ()>(args)?;
+    let html = parsed.required.0;
+    let options = build_conversion_options(ruby, parsed.optional.0)?;
+
+    #[cfg(feature = "metadata")]
+    let metadata_config = Some(build_metadata_config(ruby, parsed.optional.1)?);
+    #[cfg(not(feature = "metadata"))]
+    let metadata_config: Option<()> = None;
+
+    let result =
+        guard_panic(|| convert_with_tables_inner(&html, Some(options), metadata_config)).map_err(conversion_error)?;
+
+    tables_result_to_ruby(ruby, result)
+}
+
 #[cfg(feature = "visitor")]
 fn convert_with_visitor_fn(ruby: &Ruby, args: &[Value]) -> Result<String, Error> {
     let parsed = scan_args::<(String,), (Option<Value>, Option<Value>), (), (), (), ()>(args)?;
@@ -227,7 +250,10 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     }
 
     #[cfg(feature = "visitor")]
-    module.define_singleton_method("convert_with_visitor", function!(convert_with_visitor_fn, -1))?;
+    {
+        module.define_singleton_method("convert_with_visitor", function!(convert_with_visitor_fn, -1))?;
+        module.define_singleton_method("convert_with_tables", function!(convert_with_tables_fn, -1))?;
+    }
 
     #[cfg(feature = "profiling")]
     {

data/lib/html_to_markdown/version.rb

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

data/lib/html_to_markdown.rb

@@ -18,6 +18,7 @@ module HtmlToMarkdown
     alias native_convert_with_metadata convert_with_metadata
     alias native_convert_with_metadata_handle convert_with_metadata_handle
     alias native_convert_with_visitor convert_with_visitor
+    alias native_convert_with_tables convert_with_tables
   end
 
   module_function
@@ -179,4 +180,32 @@ module HtmlToMarkdown
   def convert_with_metadata_handle(html, options_handle, metadata_config = nil)
     native_convert_with_metadata_handle(html.to_s, options_handle, metadata_config)
   end
+
+  # Convert HTML to Markdown with table extraction.
+  #
+  # Performs HTML-to-Markdown conversion while extracting structured table data
+  # (cells, markdown representation, header row flags) in a single pass.
+  #
+  # @param html [String] HTML string to convert.
+  # @param options [Hash, nil] Optional conversion configuration.
+  # @param metadata_config [Hash, nil] Optional metadata extraction configuration.
+  #
+  # @return [Hash] A hash with keys:
+  #   - :content [String] The converted Markdown output
+  #   - :metadata [Hash, nil] Extended metadata (if metadata extraction was configured)
+  #   - :tables [Array<Hash>] Extracted tables, each with:
+  #     - :cells [Array<Array<String>>] Table cells organized as rows x columns
+  #     - :markdown [String] Complete rendered table in Markdown format
+  #     - :is_header_row [Array<Boolean>] Per-row flag indicating header rows
+  #
+  # @raise [StandardError] If conversion fails or invalid configuration
+  #
+  # @example Basic usage
+  #   html = '<table><thead><tr><th>Name</th></tr></thead><tbody><tr><td>Alice</td></tr></tbody></table>'
+  #   result = HtmlToMarkdown.convert_with_tables(html)
+  #   puts result[:tables].length    # => 1
+  #   puts result[:tables][0][:cells] # => [["Name"], ["Alice"]]
+  def convert_with_tables(html, options = nil, metadata_config = nil)
+    native_convert_with_tables(html.to_s, options, metadata_config)
+  end
 end

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

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

data/rust-vendor/html-to-markdown-rs/README.md

@@ -148,6 +148,35 @@ for (i, img) in extraction.inline_images.iter().enumerate() {
 }
 ```
 
+## Table Extraction
+
+Extract structured table data alongside the Markdown conversion. Each table found in the HTML is returned with its cell contents, header row flags, and rendered Markdown output.
+
+Requires the `visitor` feature.
+
+```rust
+use html_to_markdown_rs::convert_with_tables;
+
+let html = r#"
+<table>
+    <tr><th>Name</th><th>Age</th></tr>
+    <tr><td>Alice</td><td>30</td></tr>
+    <tr><td>Bob</td><td>25</td></tr>
+</table>
+"#;
+
+let result = convert_with_tables(html, None, None)?;
+
+println!("{}", result.content);
+for table in &result.tables {
+    println!("Table with {} rows:", table.cells.len());
+    for (i, row) in table.cells.iter().enumerate() {
+        let prefix = if table.is_header_row[i] { "Header" } else { "Row" };
+        println!("  {}: {:?}", prefix, row);
+    }
+}
+```
+
 ## Other Language Bindings
 
 This is the core Rust library. For other languages:

data/rust-vendor/html-to-markdown-rs/src/convert_api.rs

@@ -681,3 +681,371 @@ pub fn metadata_config_from_json(json: &str) -> Result<MetadataConfig> {
     let update: crate::MetadataConfigUpdate = parse_json(json)?;
     Ok(MetadataConfig::from(update))
 }
+
+// ============================================================================
+// Table Extraction API (requires visitor feature)
+// ============================================================================
+
+/// Extracted table data from HTML conversion.
+///
+/// Each instance represents a single `<table>` element found during conversion.
+/// Tables are collected in document order.
+#[cfg(feature = "visitor")]
+#[derive(Debug, Clone)]
+#[cfg_attr(
+    any(feature = "serde", feature = "metadata"),
+    derive(serde::Serialize, serde::Deserialize)
+)]
+pub struct TableData {
+    /// Table cells organized as rows x columns. Cell contents are already
+    /// converted to the target output format (markdown/djot/plain).
+    pub cells: Vec<Vec<String>>,
+    /// Complete rendered table in the target output format.
+    pub markdown: String,
+    /// Per-row flag indicating whether the row was inside `<thead>`.
+    pub is_header_row: Vec<bool>,
+}
+
+/// Result of HTML-to-markdown conversion with extracted table data.
+#[cfg(feature = "visitor")]
+#[derive(Debug, Clone)]
+#[cfg_attr(
+    any(feature = "serde", feature = "metadata"),
+    derive(serde::Serialize, serde::Deserialize)
+)]
+pub struct ConversionWithTables {
+    /// Converted markdown/djot/plain text content.
+    pub content: String,
+    /// Extended metadata (if metadata extraction was requested).
+    #[cfg(feature = "metadata")]
+    pub metadata: Option<ExtendedMetadata>,
+    /// All tables found in the HTML, in document order.
+    pub tables: Vec<TableData>,
+}
+
+#[cfg(feature = "visitor")]
+#[derive(Debug)]
+struct TableCollector {
+    tables: Vec<TableData>,
+    current_rows: Vec<Vec<String>>,
+    current_is_header: Vec<bool>,
+}
+
+#[cfg(feature = "visitor")]
+impl TableCollector {
+    fn new() -> Self {
+        Self {
+            tables: Vec::new(),
+            current_rows: Vec::new(),
+            current_is_header: Vec::new(),
+        }
+    }
+}
+
+#[cfg(feature = "visitor")]
+impl visitor::HtmlVisitor for TableCollector {
+    fn visit_table_start(&mut self, _ctx: &visitor::NodeContext) -> visitor::VisitResult {
+        self.current_rows.clear();
+        self.current_is_header.clear();
+        visitor::VisitResult::Continue
+    }
+
+    fn visit_table_row(
+        &mut self,
+        _ctx: &visitor::NodeContext,
+        cells: &[String],
+        is_header: bool,
+    ) -> visitor::VisitResult {
+        self.current_rows.push(cells.to_vec());
+        self.current_is_header.push(is_header);
+        visitor::VisitResult::Continue
+    }
+
+    fn visit_table_end(&mut self, _ctx: &visitor::NodeContext, output: &str) -> visitor::VisitResult {
+        if !self.current_rows.is_empty() {
+            self.tables.push(TableData {
+                cells: std::mem::take(&mut self.current_rows),
+                markdown: output.to_string(),
+                is_header_row: std::mem::take(&mut self.current_is_header),
+            });
+        }
+        visitor::VisitResult::Continue
+    }
+}
+
+/// Convert HTML to markdown/djot/plain text with structured table extraction.
+///
+/// Combines conversion, optional metadata extraction, and table data collection
+/// in a single DOM walk. Each table found in the HTML is returned with its
+/// cell contents (already converted to the target format) and rendered output.
+///
+/// # Arguments
+///
+/// * `html` - The HTML string to convert
+/// * `options` - Optional conversion options (defaults to `ConversionOptions::default()`)
+/// * `metadata_cfg` - Optional metadata extraction configuration (requires `metadata` feature)
+///
+/// # Example
+///
+/// ```ignore
+/// use html_to_markdown_rs::convert_with_tables;
+///
+/// let html = r#"<table><tr><th>Name</th><th>Age</th></tr><tr><td>Alice</td><td>30</td></tr></table>"#;
+/// let result = convert_with_tables(html, None, None).unwrap();
+/// assert_eq!(result.tables.len(), 1);
+/// assert_eq!(result.tables[0].cells[0], vec!["Name", "Age"]);
+/// ```
+///
+/// # Errors
+///
+/// Returns an error if HTML parsing fails or if the input contains invalid UTF-8.
+#[cfg(feature = "visitor")]
+pub fn convert_with_tables(
+    html: &str,
+    options: Option<ConversionOptions>,
+    #[cfg(feature = "metadata")] metadata_cfg: Option<MetadataConfig>,
+    #[cfg(not(feature = "metadata"))] _metadata_cfg: Option<()>,
+) -> Result<ConversionWithTables> {
+    use std::cell::RefCell;
+    use std::rc::Rc;
+
+    let collector = Rc::new(RefCell::new(TableCollector::new()));
+    let visitor_handle: visitor::VisitorHandle = Rc::clone(&collector) as visitor::VisitorHandle;
+
+    #[cfg(feature = "metadata")]
+    let result = {
+        let metadata_config = metadata_cfg.unwrap_or_default();
+        let (content, metadata) = convert_with_metadata(html, options, metadata_config, Some(visitor_handle))?;
+        let tables = Rc::try_unwrap(collector)
+            .map_err(|_| ConversionError::Other("failed to recover table collector state".into()))?
+            .into_inner()
+            .tables;
+        ConversionWithTables {
+            content,
+            metadata: Some(metadata),
+            tables,
+        }
+    };
+
+    #[cfg(not(feature = "metadata"))]
+    let result = {
+        let content = convert_with_visitor(html, options, Some(visitor_handle))?;
+        let tables = Rc::try_unwrap(collector)
+            .map_err(|_| ConversionError::Other("failed to recover table collector state".into()))?
+            .into_inner()
+            .tables;
+        ConversionWithTables { content, tables }
+    };
+
+    Ok(result)
+}
+
+#[cfg(test)]
+#[cfg(feature = "visitor")]
+mod table_extraction_tests {
+    use super::*;
+
+    fn tables_from_html(html: &str) -> ConversionWithTables {
+        convert_with_tables(
+            html,
+            None,
+            #[cfg(feature = "metadata")]
+            None,
+            #[cfg(not(feature = "metadata"))]
+            None,
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn test_convert_with_tables_basic() {
+        let html = r#"<table><tr><th>Name</th><th>Age</th></tr><tr><td>Alice</td><td>30</td></tr></table>"#;
+        let result = tables_from_html(html);
+        assert_eq!(result.tables.len(), 1);
+        assert_eq!(result.tables[0].cells.len(), 2);
+        assert_eq!(result.tables[0].cells[0], vec!["Name", "Age"]);
+        assert_eq!(result.tables[0].cells[1], vec!["Alice", "30"]);
+        assert!(result.tables[0].is_header_row[0]);
+        assert!(!result.tables[0].is_header_row[1]);
+        assert!(result.tables[0].markdown.contains('|'));
+    }
+
+    #[test]
+    fn test_convert_with_tables_nested() {
+        let html = r#"
+        <table>
+            <tr><th>Category</th><th>Details</th></tr>
+            <tr>
+                <td>Project Alpha</td>
+                <td>
+                    <table>
+                        <tr><th>Task</th><th>Status</th></tr>
+                        <tr><td>001</td><td>Done</td></tr>
+                    </table>
+                </td>
+            </tr>
+        </table>"#;
+        let result = tables_from_html(html);
+        assert!(
+            result.tables.len() >= 2,
+            "Expected at least 2 tables (outer + nested), got {}",
+            result.tables.len()
+        );
+    }
+
+    #[test]
+    fn test_convert_with_tables_no_tables() {
+        let html = "<p>No tables here</p>";
+        let result = tables_from_html(html);
+        assert!(result.tables.is_empty());
+        assert!(result.content.contains("No tables here"));
+    }
+
+    #[test]
+    fn test_convert_with_tables_empty_table() {
+        let result = tables_from_html("<table></table>");
+        assert!(result.tables.is_empty(), "Empty table should not produce TableData");
+    }
+
+    #[test]
+    fn test_convert_with_tables_headers_only() {
+        let html = r#"<table><thead><tr><th>A</th><th>B</th></tr></thead></table>"#;
+        let result = tables_from_html(html);
+        assert_eq!(result.tables.len(), 1);
+        assert!(result.tables[0].is_header_row[0]);
+        assert_eq!(result.tables[0].cells[0], vec!["A", "B"]);
+    }
+
+    #[test]
+    fn test_convert_with_tables_thead_tbody_tfoot() {
+        let html = r#"
+        <table>
+            <thead><tr><th>H1</th></tr></thead>
+            <tbody><tr><td>B1</td></tr></tbody>
+            <tfoot><tr><td>F1</td></tr></tfoot>
+        </table>"#;
+        let result = tables_from_html(html);
+        assert_eq!(result.tables.len(), 1);
+        let t = &result.tables[0];
+        assert!(t.is_header_row[0], "thead row should be header");
+        assert!(!t.is_header_row[1], "tbody row should not be header");
+        assert_eq!(t.cells[0], vec!["H1"]);
+        assert_eq!(t.cells[1], vec!["B1"]);
+    }
+
+    #[test]
+    fn test_convert_with_tables_multiple_separate() {
+        let html = r#"
+        <table><tr><td>T1</td></tr></table>
+        <p>Between tables</p>
+        <table><tr><td>T2</td></tr></table>"#;
+        let result = tables_from_html(html);
+        assert_eq!(result.tables.len(), 2, "Should find 2 separate tables");
+    }
+
+    #[test]
+    fn test_convert_with_tables_special_chars() {
+        let html = r#"<table><tr><td>a | b</td><td>c*d</td></tr></table>"#;
+        let result = tables_from_html(html);
+        assert_eq!(result.tables.len(), 1);
+        assert!(!result.tables[0].cells[0].is_empty());
+    }
+
+    #[test]
+    fn test_convert_with_tables_single_cell() {
+        let html = r#"<table><tr><td>Only cell</td></tr></table>"#;
+        let result = tables_from_html(html);
+        assert_eq!(result.tables.len(), 1);
+        assert_eq!(result.tables[0].cells.len(), 1);
+        assert_eq!(result.tables[0].cells[0], vec!["Only cell"]);
+    }
+
+    #[test]
+    fn test_convert_with_tables_content_preserved() {
+        let html = r#"<p>Before</p><table><tr><td>Cell</td></tr></table><p>After</p>"#;
+        let result = tables_from_html(html);
+        assert!(result.content.contains("Before"));
+        assert!(result.content.contains("After"));
+        assert!(result.content.contains('|'), "Markdown table should appear in content");
+    }
+
+    #[test]
+    fn test_convert_with_tables_with_options() {
+        let options = ConversionOptions {
+            heading_style: crate::options::HeadingStyle::Underlined,
+            ..ConversionOptions::default()
+        };
+        let html = r#"<h1>Title</h1><table><tr><td>Cell</td></tr></table>"#;
+        let result = convert_with_tables(
+            html,
+            Some(options),
+            #[cfg(feature = "metadata")]
+            None,
+            #[cfg(not(feature = "metadata"))]
+            None,
+        )
+        .unwrap();
+        assert_eq!(result.tables.len(), 1);
+        assert!(result.content.contains("Title"));
+    }
+
+    #[test]
+    fn test_convert_with_tables_plain_text_format() {
+        let options = ConversionOptions {
+            output_format: crate::options::OutputFormat::Plain,
+            ..ConversionOptions::default()
+        };
+        let html = r#"<table><tr><th>Name</th></tr><tr><td>Alice</td></tr></table>"#;
+        let result = convert_with_tables(
+            html,
+            Some(options),
+            #[cfg(feature = "metadata")]
+            None,
+            #[cfg(not(feature = "metadata"))]
+            None,
+        )
+        .unwrap();
+        assert!(
+            !result.tables.is_empty(),
+            "Tables should be populated even with plain text output format"
+        );
+        assert_eq!(result.tables[0].cells[0], vec!["Name"]);
+    }
+
+    #[cfg(feature = "metadata")]
+    #[test]
+    fn test_convert_with_tables_metadata_integration() {
+        let html = r#"<html lang="en"><head><title>Test</title></head><body>
+            <table><tr><th>Col</th></tr><tr><td>Val</td></tr></table>
+        </body></html>"#;
+        let config = MetadataConfig::default();
+        let result = convert_with_tables(html, None, Some(config)).unwrap();
+        assert_eq!(result.tables.len(), 1);
+        let meta = result.metadata.as_ref().expect("metadata should be present");
+        assert_eq!(meta.document.language, Some("en".to_string()));
+    }
+
+    #[cfg(feature = "metadata")]
+    #[test]
+    fn test_convert_with_tables_plain_text_metadata() {
+        let options = ConversionOptions {
+            output_format: crate::options::OutputFormat::Plain,
+            ..ConversionOptions::default()
+        };
+        let html = r#"<html lang="fr"><body>
+            <table><tr><td>Cell</td></tr></table>
+        </body></html>"#;
+        let config = MetadataConfig::default();
+        let result = convert_with_tables(html, Some(options), Some(config)).unwrap();
+        assert!(
+            !result.tables.is_empty(),
+            "Tables should be populated in plain text mode"
+        );
+        let meta = result.metadata.as_ref().expect("metadata should be present");
+        assert_eq!(
+            meta.document.language,
+            Some("fr".to_string()),
+            "Metadata should be populated in plain text mode"
+        );
+    }
+}

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

@@ -136,11 +136,9 @@ pub(crate) fn convert_html_impl(
         }
     }
 
-    // Fast path for plain text output: skip the full conversion pipeline
-    if options.output_format == OutputFormat::Plain {
-        let plain = extract_plain_text(&dom, parser, options);
-        return Ok(plain);
-    }
+    // Plain text output: run the full pipeline (for metadata + visitor callbacks),
+    // then return plain text instead of markdown.
+    let is_plain_text = options.output_format == OutputFormat::Plain;
 
     let wants_frontmatter = options.extract_metadata && !options.convert_as_inline;
     #[cfg(feature = "metadata")]
@@ -230,6 +228,13 @@ pub(crate) fn convert_html_impl(
         return Err(crate::error::ConversionError::Visitor(err.clone()));
     }
 
+    // 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 {
+        let plain = extract_plain_text(&dom, parser, options);
+        return Ok(plain);
+    }
+
     trim_line_end_whitespace(&mut output);
     let trimmed = output.trim_end_matches('\n');
     if trimmed.is_empty() {

data/rust-vendor/html-to-markdown-rs/src/lib.rs

@@ -98,6 +98,9 @@ pub use convert_api::convert_with_metadata;
 #[cfg(feature = "visitor")]
 pub use convert_api::convert_with_visitor;
 
+#[cfg(feature = "visitor")]
+pub use convert_api::{ConversionWithTables, TableData, convert_with_tables};
+
 #[cfg(feature = "async-visitor")]
 pub use convert_api::convert_with_async_visitor;
 

data/rust-vendor/html-to-markdown-rs/src/prelude.rs

@@ -19,5 +19,8 @@ pub use crate::convert_with_metadata;
 #[cfg(feature = "visitor")]
 pub use crate::convert_with_visitor;
 
+#[cfg(feature = "visitor")]
+pub use crate::{ConversionWithTables, TableData, convert_with_tables};
+
 #[cfg(feature = "async-visitor")]
 pub use crate::convert_with_async_visitor;

data/sig/html_to_markdown.rbs

@@ -185,6 +185,18 @@ module HtmlToMarkdown
     structured_data: Array[structured_data]
   }
 
+  type table_data = {
+    cells: Array[Array[String]],
+    markdown: String,
+    is_header_row: Array[bool]
+  }
+
+  type table_extraction_result = {
+    content: String,
+    metadata: extended_metadata?,
+    tables: Array[table_data]
+  }
+
   # Native methods (implemented in Rust via Magnus/rb-sys)
   # These are aliased from the Rust extension and available as both module and instance methods
   private
@@ -217,6 +229,11 @@ module HtmlToMarkdown
     conversion_options? options,
     visitor? visitor
   ) -> String
+  def self.native_convert_with_tables: (
+    String html,
+    conversion_options? options,
+    metadata_config? metadata_config
+  ) -> table_extraction_result
 
   def native_convert: (String html, conversion_options? options) -> String
   def native_options: (conversion_options? options_hash) -> Options
@@ -246,6 +263,11 @@ module HtmlToMarkdown
     conversion_options? options,
     visitor? visitor
   ) -> String
+  def native_convert_with_tables: (
+    String html,
+    conversion_options? options,
+    metadata_config? metadata_config
+  ) -> table_extraction_result
 
   # Visitor interface for customizing conversion behavior
   type visitor = Object
@@ -422,6 +444,25 @@ module HtmlToMarkdown
     ?metadata_config metadata_config
   ) -> [String, extended_metadata]
 
+  # Convert HTML and extract tables as structured data
+  #
+  # Args:
+  #   html: HTML string to convert
+  #   options: Optional conversion configuration
+  #   metadata_config: Optional metadata extraction configuration
+  #
+  # Returns:
+  #   table_extraction_result: Hash containing content, metadata, and tables array
+  #
+  # Example:
+  #   result = HtmlToMarkdown.convert_with_tables(html)
+  #   puts result[:tables].length
+  def self.convert_with_tables: (
+    String html,
+    ?conversion_options options,
+    ?metadata_config metadata_config
+  ) -> table_extraction_result
+
   # Instance method versions (created by module_function)
   def convert: (String html, ?conversion_options options, ?visitor visitor) -> String
   def options: (?conversion_options options_hash) -> Options
@@ -449,4 +490,9 @@ module HtmlToMarkdown
     Options options_handle,
     ?metadata_config metadata_config
   ) -> [String, extended_metadata]
+  def convert_with_tables: (
+    String html,
+    ?conversion_options options,
+    ?metadata_config metadata_config
+  ) -> table_extraction_result
 end

data/spec/convert_with_tables_spec.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe HtmlToMarkdown do
+  describe '.convert_with_tables' do
+    it 'returns a hash with content, metadata, and tables keys' do
+      html = '<table><tr><td>Cell</td></tr></table>'
+      result = described_class.convert_with_tables(html)
+
+      expect(result).to be_a(Hash)
+      expect(result).to include(:content, :metadata, :tables)
+    end
+
+    context 'with a basic table with header' do
+      let(:html) do
+        <<~HTML
+          <table>
+            <thead>
+              <tr><th>Name</th><th>Age</th></tr>
+            </thead>
+            <tbody>
+              <tr><td>Alice</td><td>30</td></tr>
+            </tbody>
+          </table>
+        HTML
+      end
+
+      it 'extracts exactly one table' do
+        result = described_class.convert_with_tables(html)
+
+        expect(result[:tables].length).to eq(1)
+      end
+
+      it 'extracts cells as rows of columns' do
+        result = described_class.convert_with_tables(html)
+        table = result[:tables][0]
+
+        expect(table[:cells]).to be_an(Array)
+        expect(table[:cells].length).to eq(2)
+        expect(table[:cells][0]).to eq(%w[Name Age])
+        expect(table[:cells][1]).to eq(%w[Alice 30])
+      end
+
+      it 'provides markdown representation' do
+        result = described_class.convert_with_tables(html)
+        table = result[:tables][0]
+
+        expect(table[:markdown]).to be_a(String)
+        expect(table[:markdown]).to include('Name')
+        expect(table[:markdown]).to include('Alice')
+      end
+
+      it 'marks header rows correctly' do
+        result = described_class.convert_with_tables(html)
+        table = result[:tables][0]
+
+        expect(table[:is_header_row]).to be_an(Array)
+        expect(table[:is_header_row].length).to eq(2)
+        expect(table[:is_header_row][0]).to be true
+        expect(table[:is_header_row][1]).to be false
+      end
+
+      it 'includes converted markdown content' do
+        result = described_class.convert_with_tables(html)
+
+        expect(result[:content]).to be_a(String)
+        expect(result[:content]).not_to be_empty
+      end
+    end
+
+    context 'with empty HTML' do
+      it 'returns empty tables array' do
+        result = described_class.convert_with_tables('')
+
+        expect(result[:tables]).to eq([])
+        expect(result[:content]).to be_a(String)
+      end
+    end
+
+    context 'with HTML containing no tables' do
+      it 'returns empty tables array' do
+        html = '<p>No tables here</p>'
+        result = described_class.convert_with_tables(html)
+
+        expect(result[:tables]).to eq([])
+        expect(result[:content]).to include('No tables here')
+      end
+    end
+
+    context 'with multiple tables' do
+      let(:html) do
+        <<~HTML
+          <table>
+            <tr><th>A</th></tr>
+            <tr><td>1</td></tr>
+          </table>
+          <p>Some text between tables</p>
+          <table>
+            <tr><th>B</th><th>C</th></tr>
+            <tr><td>2</td><td>3</td></tr>
+            <tr><td>4</td><td>5</td></tr>
+          </table>
+        HTML
+      end
+
+      it 'extracts all tables' do
+        result = described_class.convert_with_tables(html)
+
+        expect(result[:tables].length).to eq(2)
+      end
+
+      it 'preserves table order' do
+        result = described_class.convert_with_tables(html)
+
+        first_table = result[:tables][0]
+        second_table = result[:tables][1]
+
+        expect(first_table[:cells][0]).to eq(['A'])
+        expect(second_table[:cells][0]).to eq(%w[B C])
+      end
+
+      it 'extracts correct row counts per table' do
+        result = described_class.convert_with_tables(html)
+
+        expect(result[:tables][0][:cells].length).to eq(2)
+        expect(result[:tables][1][:cells].length).to eq(3)
+      end
+    end
+
+    context 'with special characters in cells' do
+      let(:html) do
+        <<~HTML
+          <table>
+            <tr><th>Key</th><th>Value</th></tr>
+            <tr><td>Brackets &lt;&gt;</td><td>Ampersand &amp;</td></tr>
+            <tr><td>Quotes "double"</td><td>Quotes 'single'</td></tr>
+            <tr><td>Unicode: cafe\u0301</td><td>Emoji: test</td></tr>
+          </table>
+        HTML
+      end
+
+      it 'handles HTML entities in cells' do
+        result = described_class.convert_with_tables(html)
+        table = result[:tables][0]
+
+        expect(table[:cells][1][0]).to include('<>')
+        expect(table[:cells][1][1]).to include('&')
+      end
+
+      it 'handles quotes in cells' do
+        result = described_class.convert_with_tables(html)
+        table = result[:tables][0]
+
+        expect(table[:cells][2][0]).to include('"double"')
+        expect(table[:cells][2][1]).to include("'single'")
+      end
+
+      it 'handles unicode in cells' do
+        result = described_class.convert_with_tables(html)
+        table = result[:tables][0]
+
+        expect(table[:cells][3][0]).to be_a(String)
+      end
+    end
+
+    context 'with conversion options' do
+      it 'accepts options hash' do
+        html = '<table><tr><th>Header</th></tr><tr><td>Data</td></tr></table>'
+        result = described_class.convert_with_tables(html, { heading_style: :atx })
+
+        expect(result).to be_a(Hash)
+        expect(result[:tables].length).to eq(1)
+      end
+
+      it 'accepts nil options' do
+        html = '<table><tr><td>Data</td></tr></table>'
+        result = described_class.convert_with_tables(html, nil, nil)
+
+        expect(result).to be_a(Hash)
+        expect(result[:tables].length).to eq(1)
+      end
+    end
+
+    context 'with metadata config' do
+      it 'includes metadata when configured' do
+        html = '<html><head><title>Test</title></head><body><table><tr><td>Data</td></tr></table></body></html>'
+        result = described_class.convert_with_tables(html, nil, { extract_headers: true })
+
+        expect(result[:metadata]).to be_a(Hash).or(be_nil)
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: html-to-markdown
 version: !ruby/object:Gem::Version
-  version: 2.27.3
+  version: 2.28.0
 platform: ruby
 authors:
 - Na'aman Hirschfeld
@@ -61,6 +61,7 @@ files:
 - ext/html-to-markdown-rb/native/src/conversion/inline_images.rs
 - ext/html-to-markdown-rb/native/src/conversion/metadata.rs
 - ext/html-to-markdown-rb/native/src/conversion/mod.rs
+- ext/html-to-markdown-rb/native/src/conversion/tables.rs
 - ext/html-to-markdown-rb/native/src/lib.rs
 - ext/html-to-markdown-rb/native/src/options.rs
 - ext/html-to-markdown-rb/native/src/profiling.rs
@@ -9737,6 +9738,7 @@ files:
 - sig/open3.rbs
 - spec/cli_proxy_spec.rb
 - spec/convert_spec.rb
+- spec/convert_with_tables_spec.rb
 - spec/metadata_extraction_spec.rb
 - spec/spec_helper.rb
 - spec/visitor_issue_187_spec.rb