html-to-markdown 2.6.6 → 2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 957492df2cee14d93b3cd74ac48f819058c886ecf93b63fe3649afc0f9e19935
-  data.tar.gz: 97c0dce3aa1621c33b42d82a2c1f2253b0d02b71ea9ff6cbd7f10ad9ba3a0d22
+  metadata.gz: 92b1acd7c60d7aa288f3a73ee5d5f67e0397719f61879edd0d8fa4d8e3b09601
+  data.tar.gz: 687dabe472299a6007d1cc0462acb8a5103b6a41d63c4987788c8d915bdfe8c1
 SHA512:
-  metadata.gz: 74eb762ff081d375a44cac7265950b4648a068a5a5c9125dd8d4f8aa3ca1a3a6083c2bc37f393ae4ade99ce15958bbf12a7d908881760ac28985aafb93f6c92f
-  data.tar.gz: 80ab5cefd151fb887ddd792875d16146228253dc32d4b31d3ab3b033b25726a85ccbee345d7bdb71ee592de7ce882ad648b45dd92f79076a2b7ed04c8bec81b9
+  metadata.gz: c98e25f2a37a2cedec0fa611e0460aaa6f26e7be19b3fba461f9a5a4fa6ebcc8bd76e0698489e1ba0c5e8a8a172596e67cdae9ba8dc0409c7466fb34329adb93
+  data.tar.gz: 8cea9bc49e6156ce2242c155959793bd778f8747aaa6f343a8eec8d14285d503b2ef659d3cc3304b955f614dbc8fe123c7e2b7a878d6ddc965ae0a4350fab443

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    html-to-markdown (2.6.6)
+    html-to-markdown (2.7.1)
       rb_sys (>= 0.9, < 1.0)
 
 GEM

data/README.md

@@ -62,6 +62,23 @@ Apple M4 • Real Wikipedia documents • `HtmlToMarkdown.convert` (Ruby)
 
 > Same core, same benchmarks: the Ruby extension stays within single-digit % of the Rust CLI and mirrors the Python/Node numbers.
 
+### Benchmark Fixtures (Apple M4)
+
+Measured via `task bench:bindings -- --language ruby` with the shared Wikipedia + hOCR suite:
+
+| Document               | Size   | ops/sec (Ruby) |
+| ---------------------- | ------ | -------------- |
+| Lists (Timeline)       | 129 KB | 1,349          |
+| Tables (Countries)     | 360 KB | 326            |
+| Medium (Python)        | 657 KB | 157            |
+| Large (Rust)           | 567 KB | 174            |
+| Small (Intro)          | 463 KB | 214            |
+| hOCR German PDF        | 44 KB  | 2,936          |
+| hOCR Invoice           | 4 KB   | 25,740         |
+| hOCR Embedded Tables   | 37 KB  | 3,328          |
+
+> These numbers line up with the Python/Node bindings because everything flows through the same Rust engine.
+
 ## Quick Start
 
 ```ruby
@@ -109,6 +126,18 @@ markdown = HtmlToMarkdown.convert(
 puts markdown
 ```
 
+### Reusing Options
+
+If you’re running tight loops or benchmarks, build the options once and pass the handle back into `convert_with_options`:
+
+```ruby
+handle = HtmlToMarkdown.options(hocr_spatial_tables: false)
+
+100.times do
+  HtmlToMarkdown.convert_with_options('<h1>Handles</h1>', handle)
+end
+```
+
 ### HTML Preprocessing
 
 Clean up scraped HTML (navigation, forms, malformed markup) before conversion:

data/bin/benchmark.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require 'time'
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'html_to_markdown'
+
+def json_escape(value)
+  value.to_s.gsub(/["\\\n\r]/) do |char|
+    case char
+    when '"', '\\'
+      "\\#{char}"
+    when "\n"
+      '\\n'
+    when "\r"
+      '\\r'
+    end
+  end
+end
+
+options = {
+  iterations: 50,
+  format: 'html'
+}
+
+OptionParser.new do |parser|
+  parser.banner = 'ruby benchmark.rb --file path/to/fixture.html [--iterations 200]'
+
+  parser.on('--file FILE', 'HTML fixture to convert repeatedly') do |file|
+    options[:file] = file
+  end
+
+  parser.on('--iterations N', Integer, 'Number of conversion iterations (default: 50)') do |n|
+    options[:iterations] = n.positive? ? n : 1
+  end
+
+  parser.on('--format FORMAT', 'Fixture format (html or hocr)') do |format|
+    options[:format] = format.downcase
+  end
+end.parse!
+
+fixture = options.fetch(:file) do
+  warn 'Missing --file parameter'
+  exit 1
+end
+
+unless File.exist?(fixture)
+  warn "Fixture not found: #{fixture}"
+  exit 1
+end
+
+unless %w[html hocr].include?(options[:format])
+  warn "Unsupported format: #{options[:format]}"
+  exit 1
+end
+
+html = File.binread(fixture)
+html.force_encoding(Encoding::UTF_8)
+html.freeze
+iterations = options[:iterations]
+options_handle = HtmlToMarkdown.options(
+  options[:format] == 'hocr' ? { hocr_spatial_tables: false } : nil
+)
+
+def convert_document(html, options_handle)
+  HtmlToMarkdown.convert_with_options(html, options_handle)
+end
+
+convert_document(html, options_handle)
+
+start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+iterations.times { convert_document(html, options_handle) }
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+payload_size_bytes = html.bytesize
+bytes_processed = payload_size_bytes * iterations
+ops_per_sec = iterations / elapsed
+mb_per_sec = (bytes_processed.to_f / (1024 * 1024)) / elapsed
+
+payload = %({
+  "language":"ruby",
+  "fixture":"#{json_escape(File.basename(fixture))}",
+  "fixture_path":"#{json_escape(fixture)}",
+  "iterations":#{iterations},
+  "elapsed_seconds":#{format('%.8f', elapsed)},
+  "ops_per_sec":#{format('%.4f', ops_per_sec)},
+  "mb_per_sec":#{format('%.4f', mb_per_sec)},
+  "bytes_processed":#{bytes_processed},
+  "payload_size_bytes":#{payload_size_bytes}
+})
+
+puts payload.strip

data/ext/html-to-markdown-rb/extconf.rb

@@ -3,6 +3,7 @@
 require 'mkmf'
 require 'rb_sys/mkmf'
 require 'rbconfig'
+require 'pathname'
 
 if RbConfig::CONFIG['host_os'] =~ /mswin|mingw/
   devkit = ENV.fetch('RI_DEVKIT', nil)
@@ -24,5 +25,14 @@ default_profile = ENV.fetch('CARGO_PROFILE', 'release')
 
 create_rust_makefile('html_to_markdown_rb') do |config|
   config.profile = default_profile.to_sym
-  config.ext_dir = File.expand_path('native', __dir__)
+
+  native_dir = File.expand_path('native', __dir__)
+  relative_native =
+    begin
+      Pathname.new(native_dir).relative_path_from(Pathname.new(__dir__)).to_s
+    rescue ArgumentError
+      native_dir
+    end
+
+  config.ext_dir = relative_native
 end

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

@@ -1,6 +1,6 @@
 [package]
 name = "html-to-markdown-rb"
-version = "2.6.6"
+version = "2.7.1"
 edition = "2024"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
 license = "MIT"
@@ -21,7 +21,7 @@ crate-type = ["cdylib", "rlib"]
 default = []
 
 [dependencies]
-html-to-markdown-rs = { version = "2.6.5", features = ["inline-images"] }
+html-to-markdown-rs = { version = "2.7.1", features = ["inline-images"] }
 magnus = { git = "https://github.com/matsadler/magnus", rev = "f6db11769efb517427bf7f121f9c32e18b059b38", features = ["rb-sys"] }
 
 [dev-dependencies]

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

@@ -5,8 +5,13 @@ use html_to_markdown_rs::{
     convert_with_inline_images as convert_with_inline_images_inner, error::ConversionError,
 };
 use magnus::prelude::*;
+use magnus::r_hash::ForEach;
 use magnus::{Error, RArray, RHash, Ruby, Symbol, TryConvert, Value, function, scan_args::scan_args};
 
+#[derive(Clone)]
+#[magnus::wrap(class = "HtmlToMarkdown::Options", free_immediately)]
+struct OptionsHandle(ConversionOptions);
+
 const DEFAULT_INLINE_IMAGE_LIMIT: u64 = 5 * 1024 * 1024;
 
 fn conversion_error(err: ConversionError) -> Error {
@@ -34,11 +39,6 @@ fn symbol_to_string(value: Value) -> Result<String, Error> {
     }
 }
 
-fn get_kw(ruby: &Ruby, hash: RHash, name: &str) -> Option<Value> {
-    let sym = ruby.intern(name);
-    hash.get(sym).or_else(|| hash.get(name))
-}
-
 fn parse_heading_style(value: Value) -> Result<HeadingStyle, Error> {
     match symbol_to_string(value)?.as_str() {
         "underlined" => Ok(HeadingStyle::Underlined),
@@ -106,26 +106,30 @@ fn parse_vec_of_strings(value: Value) -> Result<Vec<String>, Error> {
     array.to_vec::<String>()
 }
 
-fn parse_preprocessing_options(ruby: &Ruby, value: Value) -> Result<PreprocessingOptions, Error> {
+fn parse_preprocessing_options(_ruby: &Ruby, value: Value) -> Result<PreprocessingOptions, Error> {
     let hash = RHash::from_value(value).ok_or_else(|| arg_error("expected preprocessing to be a Hash"))?;
 
     let mut opts = PreprocessingOptions::default();
 
-    if let Some(enabled) = get_kw(ruby, hash, "enabled") {
-        opts.enabled = bool::try_convert(enabled)?;
-    }
-
-    if let Some(preset) = get_kw(ruby, hash, "preset") {
-        opts.preset = parse_preset(preset)?;
-    }
-
-    if let Some(remove_navigation) = get_kw(ruby, hash, "remove_navigation") {
-        opts.remove_navigation = bool::try_convert(remove_navigation)?;
-    }
-
-    if let Some(remove_forms) = get_kw(ruby, hash, "remove_forms") {
-        opts.remove_forms = bool::try_convert(remove_forms)?;
-    }
+    hash.foreach(|key: Value, val: Value| {
+        let key_name = symbol_to_string(key)?;
+        match key_name.as_str() {
+            "enabled" => {
+                opts.enabled = bool::try_convert(val)?;
+            }
+            "preset" => {
+                opts.preset = parse_preset(val)?;
+            }
+            "remove_navigation" => {
+                opts.remove_navigation = bool::try_convert(val)?;
+            }
+            "remove_forms" => {
+                opts.remove_forms = bool::try_convert(val)?;
+            }
+            _ => {}
+        }
+        Ok(ForEach::Continue)
+    })?;
 
     Ok(opts)
 }
@@ -143,142 +147,119 @@ fn build_conversion_options(ruby: &Ruby, options: Option<Value>) -> Result<Conve
 
     let hash = RHash::from_value(options).ok_or_else(|| arg_error("options must be provided as a Hash"))?;
 
-    if let Some(heading_style) = get_kw(ruby, hash, "heading_style") {
-        opts.heading_style = parse_heading_style(heading_style)?;
-    }
-
-    if let Some(list_indent_type) = get_kw(ruby, hash, "list_indent_type") {
-        opts.list_indent_type = parse_list_indent_type(list_indent_type)?;
-    }
-
-    if let Some(list_indent_width) = get_kw(ruby, hash, "list_indent_width") {
-        opts.list_indent_width = usize::try_convert(list_indent_width)?;
-    }
-
-    if let Some(bullets) = get_kw(ruby, hash, "bullets") {
-        opts.bullets = String::try_convert(bullets)?;
-    }
-
-    if let Some(strong_em_symbol) = get_kw(ruby, hash, "strong_em_symbol") {
-        let value = String::try_convert(strong_em_symbol)?;
-        let mut chars = value.chars();
-        let ch = chars
-            .next()
-            .ok_or_else(|| arg_error("strong_em_symbol must not be empty"))?;
-        if chars.next().is_some() {
-            return Err(arg_error("strong_em_symbol must be a single character"));
+    hash.foreach(|key: Value, val: Value| {
+        let key_name = symbol_to_string(key)?;
+        match key_name.as_str() {
+            "heading_style" => {
+                opts.heading_style = parse_heading_style(val)?;
+            }
+            "list_indent_type" => {
+                opts.list_indent_type = parse_list_indent_type(val)?;
+            }
+            "list_indent_width" => {
+                opts.list_indent_width = usize::try_convert(val)?;
+            }
+            "bullets" => {
+                opts.bullets = String::try_convert(val)?;
+            }
+            "strong_em_symbol" => {
+                let value = String::try_convert(val)?;
+                let mut chars = value.chars();
+                let ch = chars
+                    .next()
+                    .ok_or_else(|| arg_error("strong_em_symbol must not be empty"))?;
+                if chars.next().is_some() {
+                    return Err(arg_error("strong_em_symbol must be a single character"));
+                }
+                opts.strong_em_symbol = ch;
+            }
+            "escape_asterisks" => {
+                opts.escape_asterisks = bool::try_convert(val)?;
+            }
+            "escape_underscores" => {
+                opts.escape_underscores = bool::try_convert(val)?;
+            }
+            "escape_misc" => {
+                opts.escape_misc = bool::try_convert(val)?;
+            }
+            "escape_ascii" => {
+                opts.escape_ascii = bool::try_convert(val)?;
+            }
+            "code_language" => {
+                opts.code_language = String::try_convert(val)?;
+            }
+            "autolinks" => {
+                opts.autolinks = bool::try_convert(val)?;
+            }
+            "default_title" => {
+                opts.default_title = bool::try_convert(val)?;
+            }
+            "br_in_tables" => {
+                opts.br_in_tables = bool::try_convert(val)?;
+            }
+            "hocr_spatial_tables" => {
+                opts.hocr_spatial_tables = bool::try_convert(val)?;
+            }
+            "highlight_style" => {
+                opts.highlight_style = parse_highlight_style(val)?;
+            }
+            "extract_metadata" => {
+                opts.extract_metadata = bool::try_convert(val)?;
+            }
+            "whitespace_mode" => {
+                opts.whitespace_mode = parse_whitespace_mode(val)?;
+            }
+            "strip_newlines" => {
+                opts.strip_newlines = bool::try_convert(val)?;
+            }
+            "wrap" => {
+                opts.wrap = bool::try_convert(val)?;
+            }
+            "wrap_width" => {
+                opts.wrap_width = usize::try_convert(val)?;
+            }
+            "convert_as_inline" => {
+                opts.convert_as_inline = bool::try_convert(val)?;
+            }
+            "sub_symbol" => {
+                opts.sub_symbol = String::try_convert(val)?;
+            }
+            "sup_symbol" => {
+                opts.sup_symbol = String::try_convert(val)?;
+            }
+            "newline_style" => {
+                opts.newline_style = parse_newline_style(val)?;
+            }
+            "code_block_style" => {
+                opts.code_block_style = parse_code_block_style(val)?;
+            }
+            "keep_inline_images_in" => {
+                opts.keep_inline_images_in = parse_vec_of_strings(val)?;
+            }
+            "preprocessing" => {
+                opts.preprocessing = parse_preprocessing_options(ruby, val)?;
+            }
+            "encoding" => {
+                opts.encoding = String::try_convert(val)?;
+            }
+            "debug" => {
+                opts.debug = bool::try_convert(val)?;
+            }
+            "strip_tags" => {
+                opts.strip_tags = parse_vec_of_strings(val)?;
+            }
+            "preserve_tags" => {
+                opts.preserve_tags = parse_vec_of_strings(val)?;
+            }
+            _ => {}
         }
-        opts.strong_em_symbol = ch;
-    }
-
-    if let Some(escape_asterisks) = get_kw(ruby, hash, "escape_asterisks") {
-        opts.escape_asterisks = bool::try_convert(escape_asterisks)?;
-    }
-
-    if let Some(escape_underscores) = get_kw(ruby, hash, "escape_underscores") {
-        opts.escape_underscores = bool::try_convert(escape_underscores)?;
-    }
-
-    if let Some(escape_misc) = get_kw(ruby, hash, "escape_misc") {
-        opts.escape_misc = bool::try_convert(escape_misc)?;
-    }
-
-    if let Some(escape_ascii) = get_kw(ruby, hash, "escape_ascii") {
-        opts.escape_ascii = bool::try_convert(escape_ascii)?;
-    }
-
-    if let Some(code_language) = get_kw(ruby, hash, "code_language") {
-        opts.code_language = String::try_convert(code_language)?;
-    }
-
-    if let Some(autolinks) = get_kw(ruby, hash, "autolinks") {
-        opts.autolinks = bool::try_convert(autolinks)?;
-    }
-
-    if let Some(default_title) = get_kw(ruby, hash, "default_title") {
-        opts.default_title = bool::try_convert(default_title)?;
-    }
-
-    if let Some(br_in_tables) = get_kw(ruby, hash, "br_in_tables") {
-        opts.br_in_tables = bool::try_convert(br_in_tables)?;
-    }
-
-    if let Some(hocr_spatial_tables) = get_kw(ruby, hash, "hocr_spatial_tables") {
-        opts.hocr_spatial_tables = bool::try_convert(hocr_spatial_tables)?;
-    }
-
-    if let Some(highlight_style) = get_kw(ruby, hash, "highlight_style") {
-        opts.highlight_style = parse_highlight_style(highlight_style)?;
-    }
-
-    if let Some(extract_metadata) = get_kw(ruby, hash, "extract_metadata") {
-        opts.extract_metadata = bool::try_convert(extract_metadata)?;
-    }
-
-    if let Some(whitespace_mode) = get_kw(ruby, hash, "whitespace_mode") {
-        opts.whitespace_mode = parse_whitespace_mode(whitespace_mode)?;
-    }
-
-    if let Some(strip_newlines) = get_kw(ruby, hash, "strip_newlines") {
-        opts.strip_newlines = bool::try_convert(strip_newlines)?;
-    }
-
-    if let Some(wrap) = get_kw(ruby, hash, "wrap") {
-        opts.wrap = bool::try_convert(wrap)?;
-    }
-
-    if let Some(wrap_width) = get_kw(ruby, hash, "wrap_width") {
-        opts.wrap_width = usize::try_convert(wrap_width)?;
-    }
-
-    if let Some(convert_as_inline) = get_kw(ruby, hash, "convert_as_inline") {
-        opts.convert_as_inline = bool::try_convert(convert_as_inline)?;
-    }
-
-    if let Some(sub_symbol) = get_kw(ruby, hash, "sub_symbol") {
-        opts.sub_symbol = String::try_convert(sub_symbol)?;
-    }
-
-    if let Some(sup_symbol) = get_kw(ruby, hash, "sup_symbol") {
-        opts.sup_symbol = String::try_convert(sup_symbol)?;
-    }
-
-    if let Some(newline_style) = get_kw(ruby, hash, "newline_style") {
-        opts.newline_style = parse_newline_style(newline_style)?;
-    }
-
-    if let Some(code_block_style) = get_kw(ruby, hash, "code_block_style") {
-        opts.code_block_style = parse_code_block_style(code_block_style)?;
-    }
-
-    if let Some(keep_inline_images_in) = get_kw(ruby, hash, "keep_inline_images_in") {
-        opts.keep_inline_images_in = parse_vec_of_strings(keep_inline_images_in)?;
-    }
-
-    if let Some(preprocessing) = get_kw(ruby, hash, "preprocessing") {
-        opts.preprocessing = parse_preprocessing_options(ruby, preprocessing)?;
-    }
-
-    if let Some(encoding) = get_kw(ruby, hash, "encoding") {
-        opts.encoding = String::try_convert(encoding)?;
-    }
-
-    if let Some(debug) = get_kw(ruby, hash, "debug") {
-        opts.debug = bool::try_convert(debug)?;
-    }
-
-    if let Some(strip_tags) = get_kw(ruby, hash, "strip_tags") {
-        opts.strip_tags = parse_vec_of_strings(strip_tags)?;
-    }
-
-    if let Some(preserve_tags) = get_kw(ruby, hash, "preserve_tags") {
-        opts.preserve_tags = parse_vec_of_strings(preserve_tags)?;
-    }
+        Ok(ForEach::Continue)
+    })?;
 
     Ok(opts)
 }
 
-fn build_inline_image_config(ruby: &Ruby, config: Option<Value>) -> Result<InlineImageConfig, Error> {
+fn build_inline_image_config(_ruby: &Ruby, config: Option<Value>) -> Result<InlineImageConfig, Error> {
     let mut cfg = InlineImageConfig::new(DEFAULT_INLINE_IMAGE_LIMIT);
 
     let Some(config) = config else {
@@ -291,25 +272,29 @@ fn build_inline_image_config(ruby: &Ruby, config: Option<Value>) -> Result<Inlin
 
     let hash = RHash::from_value(config).ok_or_else(|| arg_error("inline image config must be provided as a Hash"))?;
 
-    if let Some(limit) = get_kw(ruby, hash, "max_decoded_size_bytes") {
-        cfg.max_decoded_size_bytes = u64::try_convert(limit)?;
-    }
-
-    if let Some(prefix) = get_kw(ruby, hash, "filename_prefix") {
-        cfg.filename_prefix = if prefix.is_nil() {
-            None
-        } else {
-            Some(String::try_convert(prefix)?)
-        };
-    }
-
-    if let Some(capture_svg) = get_kw(ruby, hash, "capture_svg") {
-        cfg.capture_svg = bool::try_convert(capture_svg)?;
-    }
-
-    if let Some(infer_dimensions) = get_kw(ruby, hash, "infer_dimensions") {
-        cfg.infer_dimensions = bool::try_convert(infer_dimensions)?;
-    }
+    hash.foreach(|key: Value, val: Value| {
+        let key_name = symbol_to_string(key)?;
+        match key_name.as_str() {
+            "max_decoded_size_bytes" => {
+                cfg.max_decoded_size_bytes = u64::try_convert(val)?;
+            }
+            "filename_prefix" => {
+                cfg.filename_prefix = if val.is_nil() {
+                    None
+                } else {
+                    Some(String::try_convert(val)?)
+                };
+            }
+            "capture_svg" => {
+                cfg.capture_svg = bool::try_convert(val)?;
+            }
+            "infer_dimensions" => {
+                cfg.infer_dimensions = bool::try_convert(val)?;
+            }
+            _ => {}
+        }
+        Ok(ForEach::Continue)
+    })?;
 
     Ok(cfg)
 }
@@ -408,6 +393,19 @@ fn convert_fn(ruby: &Ruby, args: &[Value]) -> Result<String, Error> {
     convert_inner(&html, Some(options)).map_err(conversion_error)
 }
 
+fn options_handle_fn(ruby: &Ruby, args: &[Value]) -> Result<OptionsHandle, Error> {
+    let parsed = scan_args::<(), (Option<Value>,), (), (), (), ()>(args)?;
+    let options = build_conversion_options(ruby, parsed.optional.0)?;
+    Ok(OptionsHandle(options))
+}
+
+fn convert_with_options_handle_fn(_ruby: &Ruby, args: &[Value]) -> Result<String, Error> {
+    let parsed = scan_args::<(String, &OptionsHandle), (), (), (), (), ()>(args)?;
+    let html = parsed.required.0;
+    let handle = parsed.required.1;
+    convert_inner(&html, Some(handle.0.clone())).map_err(conversion_error)
+}
+
 fn convert_with_inline_images_fn(ruby: &Ruby, args: &[Value]) -> Result<Value, Error> {
     let parsed = scan_args::<(String,), (Option<Value>, Option<Value>), (), (), (), ()>(args)?;
     let html = parsed.required.0;
@@ -423,6 +421,8 @@ fn convert_with_inline_images_fn(ruby: &Ruby, args: &[Value]) -> Result<Value, E
 fn init(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("HtmlToMarkdown")?;
     module.define_singleton_method("convert", function!(convert_fn, -1))?;
+    module.define_singleton_method("options", function!(options_handle_fn, -1))?;
+    module.define_singleton_method("convert_with_options", function!(convert_with_options_handle_fn, -1))?;
     module.define_singleton_method(
         "convert_with_inline_images",
         function!(convert_with_inline_images_fn, -1),

data/lib/html_to_markdown/version.rb

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

data/lib/html_to_markdown.rb

@@ -7,9 +7,13 @@ module HtmlToMarkdown
   autoload :CLI, 'html_to_markdown/cli'
   autoload :CLIProxy, 'html_to_markdown/cli_proxy'
 
+  class Options; end # rubocop:disable Lint/EmptyClass
+
   class << self
     alias native_convert convert
     alias native_convert_with_inline_images convert_with_inline_images
+    alias native_options options
+    alias native_convert_with_options convert_with_options
   end
 
   module_function
@@ -18,7 +22,15 @@ module HtmlToMarkdown
     native_convert(html.to_s, options)
   end
 
+  def convert_with_options(html, options_handle)
+    native_convert_with_options(html.to_s, options_handle)
+  end
+
   def convert_with_inline_images(html, options = nil, image_config = nil)
     native_convert_with_inline_images(html.to_s, options, image_config)
   end
+
+  def options(options_hash = nil)
+    native_options(options_hash)
+  end
 end

data/spec/convert_spec.rb

@@ -26,4 +26,13 @@ RSpec.describe HtmlToMarkdown do
       expect(extraction[:inline_images].first[:description]).to eq('fake')
     end
   end
+
+  describe '.options' do
+    it 'returns a reusable options handle' do
+      handle = described_class.options(heading_style: :atx_closed)
+      expect(handle).to be_a(HtmlToMarkdown::Options)
+      result = described_class.convert_with_options('<h1>Hello</h1>', handle)
+      expect(result).to include('# Hello #')
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: html-to-markdown
 version: !ruby/object:Gem::Version
-  version: 2.6.6
+  version: 2.7.1
 platform: ruby
 authors:
 - Na'aman Hirschfeld
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-10 00:00:00.000000000 Z
+date: 2025-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -47,6 +47,7 @@ files:
 - Gemfile.lock
 - README.md
 - Rakefile
+- bin/benchmark.rb
 - exe/html-to-markdown
 - ext/html-to-markdown-rb/extconf.rb
 - ext/html-to-markdown-rb/native/Cargo.toml