html-to-markdown 2.15.0 → 2.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b63f7961f8ff85d6b1af2095e9033365d35d53d7370b9b76da970ca5202c338e
-  data.tar.gz: ce6d5595eaa8796e11ab377e17cb722119512273f1c24c38a10d441fe8073a82
+  metadata.gz: 98fb6b9702672ba55302719d35311f7a38bcd020a9a7830da656f38dc527c071
+  data.tar.gz: 91fb49273a53f2c9d5dcbb592a0c5ac8c995f4e15919ea0fc8bf7b2905d418d3
 SHA512:
-  metadata.gz: a07e1a18462aeeed9fb13a6fe62ed4ad04620bc34208f7a1a8510f4949dc4dd7465a94e7cee72483db5317f14a297aa2004663fe4ddab86582be9c44980608c9
-  data.tar.gz: 77b1a8aa989c37e1d52ddefbe71c36dc1a12ac7f35923003cd266ac4689a964c90774d587d9fe9392f007f6df967d675e8039c7227bc741992e67c393824a584
+  metadata.gz: 95a0de0a0486737f904d7504a2f45b7112021a2777abba28e3df1b64560337d1b1f08978c02a3b6b3e8e5a71cac2fefa9318cecc44591512c3ea9cea149551c2
+  data.tar.gz: 5f66690cc665c690083ce01e210eb164f839c6141bb8a1ef94b18bbdc5862cde769381179db20362b0162982128d1b60097abfaccf20cf7ba1f7187d20d1038e

data/Gemfile.lock

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

data/README.md

@@ -69,18 +69,18 @@ Apple M4 • Real Wikipedia documents • `HtmlToMarkdown.convert` (Ruby)
 
 ### Benchmark Fixtures (Apple M4)
 
-Measured via `task bench:bindings -- --language ruby` with the shared Wikipedia + hOCR suite:
+Measured via `task bench:harness` 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          |
+| Lists (Timeline)       | 129 KB | 3,156          |
+| Tables (Countries)     | 360 KB | 921            |
+| Medium (Python)        | 657 KB | 469            |
+| Large (Rust)           | 567 KB | 534            |
+| Small (Intro)          | 463 KB | 629            |
+| hOCR German PDF        | 44 KB  | 7,250          |
+| hOCR Invoice           | 4 KB   | 83,883         |
+| hOCR Embedded Tables   | 37 KB  | 7,890          |
 
 > These numbers line up with the Python/Node bindings because everything flows through the same Rust engine.
 

data/bin/benchmark.rb

@@ -22,7 +22,8 @@ end
 
 options = {
   iterations: 50,
-  format: 'html'
+  format: 'html',
+  scenario: 'convert-default'
 }
 
 OptionParser.new do |parser|
@@ -36,6 +37,10 @@ OptionParser.new do |parser|
     options[:iterations] = n.positive? ? n : 1
   end
 
+  parser.on('--scenario SCENARIO', 'Scenario to benchmark') do |scenario|
+    options[:scenario] = scenario
+  end
+
   parser.on('--format FORMAT', 'Fixture format (html or hocr)') do |format|
     options[:format] = format.downcase
   end
@@ -56,24 +61,68 @@ unless %w[html hocr].include?(options[:format])
   exit 1
 end
 
+supported_scenarios = %w[
+  convert-default
+  convert-options
+  inline-images-default
+  inline-images-options
+  metadata-default
+  metadata-options
+]
+unless supported_scenarios.include?(options[:scenario])
+  warn "Unsupported scenario: #{options[:scenario]}"
+  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
-)
+conversion_options = options[:format] == 'hocr' ? { hocr_spatial_tables: false } : {}
+options_handle = if %w[convert-options inline-images-options metadata-options].include?(options[:scenario])
+                   HtmlToMarkdown.options(conversion_options)
+                 end
+
+SCENARIO_RUNNERS = {
+  'convert-default' => ->(html, _options, _handle) { HtmlToMarkdown.convert(html) },
+  'convert-options' => lambda do |html, _options, handle|
+    raise ArgumentError, 'options handle required' unless handle
+
+    HtmlToMarkdown.convert_with_options(html, handle)
+  end,
+  'inline-images-default' => ->(html, _options, _handle) { HtmlToMarkdown.convert_with_inline_images(html, nil, nil) },
+  'inline-images-options' => lambda do |html, _options, handle|
+    raise ArgumentError, 'options handle required' unless handle
+
+    HtmlToMarkdown.convert_with_inline_images_handle(html, handle, nil)
+  end,
+  'metadata-default' => ->(html, _options, _handle) { HtmlToMarkdown.convert_with_metadata(html, nil, nil) },
+  'metadata-options' => lambda do |html, _options, handle|
+    raise ArgumentError, 'options handle required' unless handle
+
+    HtmlToMarkdown.convert_with_metadata_handle(html, handle, nil)
+  end
+}.freeze
 
-def convert_document(html, options_handle)
-  HtmlToMarkdown.convert_with_options(html, options_handle)
+def run_scenario(html, scenario, options, handle)
+  runner = SCENARIO_RUNNERS.fetch(scenario) { raise ArgumentError, "Unsupported scenario: #{scenario}" }
+  runner.call(html, options, handle)
 end
 
-convert_document(html, options_handle)
+run_scenario(html, options[:scenario], conversion_options, options_handle)
+
+profile_output = ENV.fetch('HTML_TO_MARKDOWN_PROFILE_OUTPUT', nil)
+if profile_output && HtmlToMarkdown.respond_to?(:start_profiling)
+  freq = Integer(ENV.fetch('HTML_TO_MARKDOWN_PROFILE_FREQUENCY', '1000'), 10)
+  HtmlToMarkdown.start_profiling(profile_output, freq)
+end
 
 start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-iterations.times { convert_document(html, options_handle) }
+iterations.times { run_scenario(html, options[:scenario], conversion_options, options_handle) }
 elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
 
+HtmlToMarkdown.stop_profiling if profile_output && HtmlToMarkdown.respond_to?(:stop_profiling)
+
 payload_size_bytes = html.bytesize
 bytes_processed = payload_size_bytes * iterations
 ops_per_sec = iterations / elapsed
@@ -83,6 +132,7 @@ payload = %({
   "language":"ruby",
   "fixture":"#{json_escape(File.basename(fixture))}",
   "fixture_path":"#{json_escape(fixture)}",
+  "scenario":"#{json_escape(options[:scenario])}",
   "iterations":#{iterations},
   "elapsed_seconds":#{format('%.8f', elapsed)},
   "ops_per_sec":#{format('%.4f', ops_per_sec)},

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

@@ -25,6 +25,9 @@ default_profile = ENV.fetch('CARGO_PROFILE', 'release')
 
 create_rust_makefile('html_to_markdown_rb') do |config|
   config.profile = default_profile.to_sym
+  features_env = ENV.fetch('HTML_TO_MARKDOWN_CARGO_FEATURES', '')
+  features = features_env.split(',').map(&:strip).reject(&:empty?)
+  config.features = features unless features.empty?
 
   native_dir = File.expand_path('native', __dir__)
   relative_native =

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

@@ -1,6 +1,6 @@
 [package]
 name = "html-to-markdown-rb"
-version = "2.15.0"
+version = "2.16.0"
 edition = "2024"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
 license = "MIT"
@@ -17,13 +17,16 @@ categories = ["api-bindings"]
 name = "html_to_markdown_rb"
 crate-type = ["cdylib", "rlib"]
 
-[features]
-default = ["metadata"]
-metadata = ["html-to-markdown-rs/metadata"]
-
 [dependencies]
-html-to-markdown-rs = { version = "2.15.0", features = ["inline-images"] }
+html-to-markdown-rs = { version = "2.16.0", features = ["inline-images"] }
 magnus = { git = "https://github.com/matsadler/magnus", rev = "f6db11769efb517427bf7f121f9c32e18b059b38", features = ["rb-sys"] }
 
+[target.'cfg(not(target_os = "windows"))'.dependencies]
+pprof = { version = "0.15", features = ["flamegraph"], optional = true }
+
 [dev-dependencies]
 pretty_assertions = "1.4"
+[features]
+default = ["metadata"]
+metadata = ["html-to-markdown-rs/metadata"]
+profiling = ["dep:pprof"]

data/ext/html-to-markdown-rb/native/README.md

@@ -62,6 +62,21 @@ 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:harness` with the shared Wikipedia + hOCR suite:
+
+| Document               | Size   | ops/sec (Ruby) |
+| ---------------------- | ------ | -------------- |
+| Lists (Timeline)       | 129 KB | 3,156          |
+| Tables (Countries)     | 360 KB | 921            |
+| Medium (Python)        | 657 KB | 469            |
+| Large (Rust)           | 567 KB | 534            |
+| Small (Intro)          | 463 KB | 629            |
+| hOCR German PDF        | 44 KB  | 7,250          |
+| hOCR Invoice           | 4 KB   | 83,883         |
+| hOCR Embedded Tables   | 37 KB  | 7,890          |
+
 ## Quick Start
 
 ```ruby

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

@@ -1,30 +1,29 @@
 use html_to_markdown_rs::{
-    CodeBlockStyle, ConversionOptions, HeadingStyle, HighlightStyle, HtmlExtraction, InlineImage, InlineImageConfig,
-    InlineImageFormat, InlineImageSource, InlineImageWarning, ListIndentType, NewlineStyle, PreprocessingOptions,
-    PreprocessingPreset, WhitespaceMode, convert as convert_inner,
-    convert_with_inline_images as convert_with_inline_images_inner, error::ConversionError, safety::guard_panic,
+    CodeBlockStyle, ConversionOptions, ConversionOptionsUpdate, DEFAULT_INLINE_IMAGE_LIMIT, HeadingStyle,
+    HighlightStyle, HtmlExtraction, InlineImage, InlineImageConfig, InlineImageConfigUpdate, InlineImageWarning,
+    ListIndentType, NewlineStyle, PreprocessingOptionsUpdate, PreprocessingPreset, WhitespaceMode,
+    convert as convert_inner, convert_with_inline_images as convert_with_inline_images_inner, error::ConversionError,
+    safety::guard_panic,
 };
 
 #[cfg(feature = "metadata")]
 use html_to_markdown_rs::convert_with_metadata as convert_with_metadata_inner;
+mod profiling;
 #[cfg(feature = "metadata")]
 use html_to_markdown_rs::metadata::{
     DocumentMetadata as RustDocumentMetadata, ExtendedMetadata as RustExtendedMetadata,
-    HeaderMetadata as RustHeaderMetadata, ImageMetadata as RustImageMetadata, ImageType as RustImageType,
-    LinkMetadata as RustLinkMetadata, LinkType as RustLinkType, MetadataConfig as RustMetadataConfig,
-    StructuredData as RustStructuredData, StructuredDataType as RustStructuredDataType,
-    TextDirection as RustTextDirection,
+    HeaderMetadata as RustHeaderMetadata, ImageMetadata as RustImageMetadata, LinkMetadata as RustLinkMetadata,
+    MetadataConfig as RustMetadataConfig, StructuredData as RustStructuredData, TextDirection as RustTextDirection,
 };
 use magnus::prelude::*;
 use magnus::r_hash::ForEach;
 use magnus::{Error, RArray, RHash, Ruby, Symbol, TryConvert, Value, function, scan_args::scan_args};
+use std::path::PathBuf;
 
 #[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 {
     match err {
         ConversionError::ConfigError(msg) => arg_error(msg),
@@ -120,43 +119,43 @@ 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<PreprocessingOptionsUpdate, Error> {
     let hash = RHash::from_value(value).ok_or_else(|| arg_error("expected preprocessing to be a Hash"))?;
 
-    let mut opts = PreprocessingOptions::default();
+    let mut update = PreprocessingOptionsUpdate::default();
 
     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)?;
+                update.enabled = Some(bool::try_convert(val)?);
             }
             "preset" => {
-                opts.preset = parse_preset(val)?;
+                update.preset = Some(parse_preset(val)?);
             }
             "remove_navigation" => {
-                opts.remove_navigation = bool::try_convert(val)?;
+                update.remove_navigation = Some(bool::try_convert(val)?);
             }
             "remove_forms" => {
-                opts.remove_forms = bool::try_convert(val)?;
+                update.remove_forms = Some(bool::try_convert(val)?);
             }
             _ => {}
         }
         Ok(ForEach::Continue)
     })?;
 
-    Ok(opts)
+    Ok(update)
 }
 
 fn build_conversion_options(ruby: &Ruby, options: Option<Value>) -> Result<ConversionOptions, Error> {
-    let mut opts = ConversionOptions::default();
+    let mut update = ConversionOptionsUpdate::default();
 
     let Some(options) = options else {
-        return Ok(opts);
+        return Ok(ConversionOptions::default());
     };
 
     if options.is_nil() {
-        return Ok(opts);
+        return Ok(ConversionOptions::default());
     }
 
     let hash = RHash::from_value(options).ok_or_else(|| arg_error("options must be provided as a Hash"))?;
@@ -165,16 +164,16 @@ fn build_conversion_options(ruby: &Ruby, options: Option<Value>) -> Result<Conve
         let key_name = symbol_to_string(key)?;
         match key_name.as_str() {
             "heading_style" => {
-                opts.heading_style = parse_heading_style(val)?;
+                update.heading_style = Some(parse_heading_style(val)?);
             }
             "list_indent_type" => {
-                opts.list_indent_type = parse_list_indent_type(val)?;
+                update.list_indent_type = Some(parse_list_indent_type(val)?);
             }
             "list_indent_width" => {
-                opts.list_indent_width = usize::try_convert(val)?;
+                update.list_indent_width = Some(usize::try_convert(val)?);
             }
             "bullets" => {
-                opts.bullets = String::try_convert(val)?;
+                update.bullets = Some(String::try_convert(val)?);
             }
             "strong_em_symbol" => {
                 let value = String::try_convert(val)?;
@@ -185,103 +184,103 @@ fn build_conversion_options(ruby: &Ruby, options: Option<Value>) -> Result<Conve
                 if chars.next().is_some() {
                     return Err(arg_error("strong_em_symbol must be a single character"));
                 }
-                opts.strong_em_symbol = ch;
+                update.strong_em_symbol = Some(ch);
             }
             "escape_asterisks" => {
-                opts.escape_asterisks = bool::try_convert(val)?;
+                update.escape_asterisks = Some(bool::try_convert(val)?);
             }
             "escape_underscores" => {
-                opts.escape_underscores = bool::try_convert(val)?;
+                update.escape_underscores = Some(bool::try_convert(val)?);
             }
             "escape_misc" => {
-                opts.escape_misc = bool::try_convert(val)?;
+                update.escape_misc = Some(bool::try_convert(val)?);
             }
             "escape_ascii" => {
-                opts.escape_ascii = bool::try_convert(val)?;
+                update.escape_ascii = Some(bool::try_convert(val)?);
             }
             "code_language" => {
-                opts.code_language = String::try_convert(val)?;
+                update.code_language = Some(String::try_convert(val)?);
             }
             "autolinks" => {
-                opts.autolinks = bool::try_convert(val)?;
+                update.autolinks = Some(bool::try_convert(val)?);
             }
             "default_title" => {
-                opts.default_title = bool::try_convert(val)?;
+                update.default_title = Some(bool::try_convert(val)?);
             }
             "br_in_tables" => {
-                opts.br_in_tables = bool::try_convert(val)?;
+                update.br_in_tables = Some(bool::try_convert(val)?);
             }
             "hocr_spatial_tables" => {
-                opts.hocr_spatial_tables = bool::try_convert(val)?;
+                update.hocr_spatial_tables = Some(bool::try_convert(val)?);
             }
             "highlight_style" => {
-                opts.highlight_style = parse_highlight_style(val)?;
+                update.highlight_style = Some(parse_highlight_style(val)?);
             }
             "extract_metadata" => {
-                opts.extract_metadata = bool::try_convert(val)?;
+                update.extract_metadata = Some(bool::try_convert(val)?);
             }
             "whitespace_mode" => {
-                opts.whitespace_mode = parse_whitespace_mode(val)?;
+                update.whitespace_mode = Some(parse_whitespace_mode(val)?);
             }
             "strip_newlines" => {
-                opts.strip_newlines = bool::try_convert(val)?;
+                update.strip_newlines = Some(bool::try_convert(val)?);
             }
             "wrap" => {
-                opts.wrap = bool::try_convert(val)?;
+                update.wrap = Some(bool::try_convert(val)?);
             }
             "wrap_width" => {
-                opts.wrap_width = usize::try_convert(val)?;
+                update.wrap_width = Some(usize::try_convert(val)?);
             }
             "convert_as_inline" => {
-                opts.convert_as_inline = bool::try_convert(val)?;
+                update.convert_as_inline = Some(bool::try_convert(val)?);
             }
             "sub_symbol" => {
-                opts.sub_symbol = String::try_convert(val)?;
+                update.sub_symbol = Some(String::try_convert(val)?);
             }
             "sup_symbol" => {
-                opts.sup_symbol = String::try_convert(val)?;
+                update.sup_symbol = Some(String::try_convert(val)?);
             }
             "newline_style" => {
-                opts.newline_style = parse_newline_style(val)?;
+                update.newline_style = Some(parse_newline_style(val)?);
             }
             "code_block_style" => {
-                opts.code_block_style = parse_code_block_style(val)?;
+                update.code_block_style = Some(parse_code_block_style(val)?);
             }
             "keep_inline_images_in" => {
-                opts.keep_inline_images_in = parse_vec_of_strings(val)?;
+                update.keep_inline_images_in = Some(parse_vec_of_strings(val)?);
             }
             "preprocessing" => {
-                opts.preprocessing = parse_preprocessing_options(ruby, val)?;
+                update.preprocessing = Some(parse_preprocessing_options(ruby, val)?);
             }
             "encoding" => {
-                opts.encoding = String::try_convert(val)?;
+                update.encoding = Some(String::try_convert(val)?);
             }
             "debug" => {
-                opts.debug = bool::try_convert(val)?;
+                update.debug = Some(bool::try_convert(val)?);
             }
             "strip_tags" => {
-                opts.strip_tags = parse_vec_of_strings(val)?;
+                update.strip_tags = Some(parse_vec_of_strings(val)?);
             }
             "preserve_tags" => {
-                opts.preserve_tags = parse_vec_of_strings(val)?;
+                update.preserve_tags = Some(parse_vec_of_strings(val)?);
             }
             _ => {}
         }
         Ok(ForEach::Continue)
     })?;
 
-    Ok(opts)
+    Ok(ConversionOptions::from(update))
 }
 
 fn build_inline_image_config(_ruby: &Ruby, config: Option<Value>) -> Result<InlineImageConfig, Error> {
-    let mut cfg = InlineImageConfig::new(DEFAULT_INLINE_IMAGE_LIMIT);
+    let mut update = InlineImageConfigUpdate::default();
 
     let Some(config) = config else {
-        return Ok(cfg);
+        return Ok(InlineImageConfig::new(DEFAULT_INLINE_IMAGE_LIMIT));
     };
 
     if config.is_nil() {
-        return Ok(cfg);
+        return Ok(InlineImageConfig::new(DEFAULT_INLINE_IMAGE_LIMIT));
     }
 
     let hash = RHash::from_value(config).ok_or_else(|| arg_error("inline image config must be provided as a Hash"))?;
@@ -290,27 +289,27 @@ fn build_inline_image_config(_ruby: &Ruby, config: Option<Value>) -> Result<Inli
         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)?;
+                update.max_decoded_size_bytes = Some(u64::try_convert(val)?);
             }
             "filename_prefix" => {
-                cfg.filename_prefix = if val.is_nil() {
+                update.filename_prefix = if val.is_nil() {
                     None
                 } else {
                     Some(String::try_convert(val)?)
                 };
             }
             "capture_svg" => {
-                cfg.capture_svg = bool::try_convert(val)?;
+                update.capture_svg = Some(bool::try_convert(val)?);
             }
             "infer_dimensions" => {
-                cfg.infer_dimensions = bool::try_convert(val)?;
+                update.infer_dimensions = Some(bool::try_convert(val)?);
             }
             _ => {}
         }
         Ok(ForEach::Continue)
     })?;
 
-    Ok(cfg)
+    Ok(InlineImageConfig::from_update(update))
 }
 
 fn inline_image_to_value(ruby: &Ruby, image: InlineImage) -> Result<Value, Error> {
@@ -328,15 +327,7 @@ fn inline_image_to_value(ruby: &Ruby, image: InlineImage) -> Result<Value, Error
     let data_value = ruby.str_from_slice(&data);
     hash.aset(ruby.intern("data"), data_value)?;
 
-    let format_value = match format {
-        InlineImageFormat::Png => "png".to_string(),
-        InlineImageFormat::Jpeg => "jpeg".to_string(),
-        InlineImageFormat::Gif => "gif".to_string(),
-        InlineImageFormat::Bmp => "bmp".to_string(),
-        InlineImageFormat::Webp => "webp".to_string(),
-        InlineImageFormat::Svg => "svg".to_string(),
-        InlineImageFormat::Other(other) => other,
-    };
+    let format_value = format.to_string();
     hash.aset(ruby.intern("format"), format_value)?;
 
     match filename {
@@ -358,10 +349,7 @@ fn inline_image_to_value(ruby: &Ruby, image: InlineImage) -> Result<Value, Error
         hash.aset(ruby.intern("dimensions"), ruby.qnil())?;
     }
 
-    let source_value = match source {
-        InlineImageSource::ImgDataUri => "img_data_uri",
-        InlineImageSource::SvgElement => "svg_element",
-    };
+    let source_value = source.to_string();
     hash.aset(ruby.intern("source"), source_value)?;
 
     let attrs = ruby.hash_new();
@@ -404,7 +392,7 @@ fn convert_fn(ruby: &Ruby, args: &[Value]) -> Result<String, Error> {
     let html = parsed.required.0;
     let options = build_conversion_options(ruby, parsed.optional.0)?;
 
-    guard_panic(|| convert_inner(&html, Some(options))).map_err(conversion_error)
+    guard_panic(|| profiling::maybe_profile(|| convert_inner(&html, Some(options)))).map_err(conversion_error)
 }
 
 fn options_handle_fn(ruby: &Ruby, args: &[Value]) -> Result<OptionsHandle, Error> {
@@ -419,7 +407,7 @@ fn convert_with_options_handle_fn(_ruby: &Ruby, args: &[Value]) -> Result<String
     let handle = parsed.required.1;
     let options = handle.0.clone();
 
-    guard_panic(|| convert_inner(&html, Some(options))).map_err(conversion_error)
+    guard_panic(|| profiling::maybe_profile(|| convert_inner(&html, Some(options)))).map_err(conversion_error)
 }
 
 fn convert_with_inline_images_fn(ruby: &Ruby, args: &[Value]) -> Result<Value, Error> {
@@ -434,6 +422,19 @@ fn convert_with_inline_images_fn(ruby: &Ruby, args: &[Value]) -> Result<Value, E
     extraction_to_value(ruby, extraction)
 }
 
+fn convert_with_inline_images_handle_fn(ruby: &Ruby, args: &[Value]) -> Result<Value, Error> {
+    let parsed = scan_args::<(String, &OptionsHandle), (Option<Value>,), (), (), (), ()>(args)?;
+    let html = parsed.required.0;
+    let handle = parsed.required.1;
+    let options = handle.0.clone();
+    let config = build_inline_image_config(ruby, parsed.optional.0)?;
+
+    let extraction =
+        guard_panic(|| convert_with_inline_images_inner(&html, Some(options), config)).map_err(conversion_error)?;
+
+    extraction_to_value(ruby, extraction)
+}
+
 #[cfg(feature = "metadata")]
 fn build_metadata_config(_ruby: &Ruby, config: Option<Value>) -> Result<RustMetadataConfig, Error> {
     let mut cfg = RustMetadataConfig::default();
@@ -451,6 +452,9 @@ fn build_metadata_config(_ruby: &Ruby, config: Option<Value>) -> Result<RustMeta
     hash.foreach(|key: Value, val: Value| {
         let key_name = symbol_to_string(key)?;
         match key_name.as_str() {
+            "extract_document" => {
+                cfg.extract_document = bool::try_convert(val)?;
+            }
             "extract_headers" => {
                 cfg.extract_headers = bool::try_convert(val)?;
             }
@@ -492,44 +496,8 @@ fn btreemap_to_ruby_hash(ruby: &Ruby, map: std::collections::BTreeMap<String, St
 }
 
 #[cfg(feature = "metadata")]
-fn text_direction_to_string(text_direction: Option<RustTextDirection>) -> Option<&'static str> {
-    match text_direction {
-        Some(RustTextDirection::LeftToRight) => Some("ltr"),
-        Some(RustTextDirection::RightToLeft) => Some("rtl"),
-        Some(RustTextDirection::Auto) => Some("auto"),
-        None => None,
-    }
-}
-
-#[cfg(feature = "metadata")]
-fn link_type_to_string(link_type: &RustLinkType) -> &'static str {
-    match link_type {
-        RustLinkType::Anchor => "anchor",
-        RustLinkType::Internal => "internal",
-        RustLinkType::External => "external",
-        RustLinkType::Email => "email",
-        RustLinkType::Phone => "phone",
-        RustLinkType::Other => "other",
-    }
-}
-
-#[cfg(feature = "metadata")]
-fn image_type_to_string(image_type: &RustImageType) -> &'static str {
-    match image_type {
-        RustImageType::DataUri => "data_uri",
-        RustImageType::InlineSvg => "inline_svg",
-        RustImageType::External => "external",
-        RustImageType::Relative => "relative",
-    }
-}
-
-#[cfg(feature = "metadata")]
-fn structured_data_type_to_string(data_type: &RustStructuredDataType) -> &'static str {
-    match data_type {
-        RustStructuredDataType::JsonLd => "json_ld",
-        RustStructuredDataType::Microdata => "microdata",
-        RustStructuredDataType::RDFa => "rdfa",
-    }
+fn text_direction_to_string(text_direction: Option<RustTextDirection>) -> Option<String> {
+    text_direction.map(|direction| direction.to_string())
 }
 
 #[cfg(feature = "metadata")]
@@ -591,7 +559,7 @@ fn links_to_ruby(ruby: &Ruby, links: Vec<RustLinkMetadata>) -> Result<Value, Err
         hash.aset(ruby.intern("href"), link.href)?;
         hash.aset(ruby.intern("text"), link.text)?;
         hash.aset(ruby.intern("title"), opt_string_to_ruby(ruby, link.title)?)?;
-        hash.aset(ruby.intern("link_type"), link_type_to_string(&link.link_type))?;
+        hash.aset(ruby.intern("link_type"), link.link_type.to_string())?;
 
         let rel_array = ruby.ary_new();
         for r in link.rel {
@@ -626,7 +594,7 @@ fn images_to_ruby(ruby: &Ruby, images: Vec<RustImageMetadata>) -> Result<Value,
             }
         }
 
-        hash.aset(ruby.intern("image_type"), image_type_to_string(&image.image_type))?;
+        hash.aset(ruby.intern("image_type"), image.image_type.to_string())?;
         hash.aset(
             ruby.intern("attributes"),
             btreemap_to_ruby_hash(ruby, image.attributes)?,
@@ -641,10 +609,7 @@ fn structured_data_to_ruby(ruby: &Ruby, data: Vec<RustStructuredData>) -> Result
     let array = ruby.ary_new();
     for item in data {
         let hash = ruby.hash_new();
-        hash.aset(
-            ruby.intern("data_type"),
-            structured_data_type_to_string(&item.data_type),
-        )?;
+        hash.aset(ruby.intern("data_type"), item.data_type.to_string())?;
         hash.aset(ruby.intern("raw_json"), item.raw_json)?;
         hash.aset(ruby.intern("schema_type"), opt_string_to_ruby(ruby, item.schema_type)?)?;
         array.push(hash)?;
@@ -688,6 +653,41 @@ fn convert_with_metadata_fn(ruby: &Ruby, args: &[Value]) -> Result<Value, Error>
     Ok(array.as_value())
 }
 
+#[cfg(feature = "metadata")]
+fn convert_with_metadata_handle_fn(ruby: &Ruby, args: &[Value]) -> Result<Value, Error> {
+    let parsed = scan_args::<(String, &OptionsHandle), (Option<Value>,), (), (), (), ()>(args)?;
+    let html = parsed.required.0;
+    let handle = parsed.required.1;
+    let options = handle.0.clone();
+    let metadata_config = build_metadata_config(ruby, parsed.optional.0)?;
+
+    let (markdown, metadata) =
+        guard_panic(|| convert_with_metadata_inner(&html, Some(options), metadata_config)).map_err(conversion_error)?;
+
+    let array = ruby.ary_new();
+    array.push(markdown)?;
+    array.push(extended_metadata_to_ruby(ruby, metadata)?)?;
+
+    Ok(array.as_value())
+}
+
+fn start_profiling_fn(_ruby: &Ruby, args: &[Value]) -> Result<bool, Error> {
+    let output = args.first().ok_or_else(|| arg_error("output_path required"))?;
+    let output: String = String::try_convert(*output)?;
+    let freq = if let Some(value) = args.get(1) {
+        i32::try_convert(*value)?
+    } else {
+        1000
+    };
+    profiling::start(PathBuf::from(output), freq).map_err(conversion_error)?;
+    Ok(true)
+}
+
+fn stop_profiling_fn(_ruby: &Ruby, _args: &[Value]) -> Result<bool, Error> {
+    profiling::stop().map_err(conversion_error)?;
+    Ok(true)
+}
+
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("HtmlToMarkdown")?;
@@ -698,9 +698,20 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "convert_with_inline_images",
         function!(convert_with_inline_images_fn, -1),
     )?;
+    module.define_singleton_method(
+        "convert_with_inline_images_handle",
+        function!(convert_with_inline_images_handle_fn, -1),
+    )?;
 
     #[cfg(feature = "metadata")]
     module.define_singleton_method("convert_with_metadata", function!(convert_with_metadata_fn, -1))?;
+    #[cfg(feature = "metadata")]
+    module.define_singleton_method(
+        "convert_with_metadata_handle",
+        function!(convert_with_metadata_handle_fn, -1),
+    )?;
+    module.define_singleton_method("start_profiling", function!(start_profiling_fn, -1))?;
+    module.define_singleton_method("stop_profiling", function!(stop_profiling_fn, -1))?;
 
     Ok(())
 }

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

@@ -0,0 +1,211 @@
+use html_to_markdown_rs::{ConversionError, Result};
+use std::path::PathBuf;
+
+#[cfg(all(not(target_os = "windows"), feature = "profiling"))]
+mod enabled {
+    use super::{ConversionError, PathBuf, Result};
+    use std::sync::atomic::{AtomicBool, Ordering};
+    use std::sync::{Mutex, OnceLock};
+
+    const ENV_OUTPUT: &str = "HTML_TO_MARKDOWN_PROFILE_OUTPUT";
+    const ENV_FREQUENCY: &str = "HTML_TO_MARKDOWN_PROFILE_FREQUENCY";
+    const ENV_ONCE: &str = "HTML_TO_MARKDOWN_PROFILE_ONCE";
+
+    static PROFILED_ONCE: AtomicBool = AtomicBool::new(false);
+    static PROFILE_ACTIVE: AtomicBool = AtomicBool::new(false);
+
+    struct EnvProfileConfig {
+        output: Option<PathBuf>,
+        profile_once: bool,
+        frequency: i32,
+    }
+
+    fn env_profile_config() -> &'static EnvProfileConfig {
+        static ENV_CONFIG: OnceLock<EnvProfileConfig> = OnceLock::new();
+        ENV_CONFIG.get_or_init(|| {
+            let output = match std::env::var(ENV_OUTPUT) {
+                Ok(value) if !value.trim().is_empty() => Some(PathBuf::from(value)),
+                _ => None,
+            };
+
+            let profile_once = match std::env::var(ENV_ONCE) {
+                Ok(value) => !matches!(value.as_str(), "0" | "false" | "no"),
+                Err(_) => true,
+            };
+
+            let frequency = std::env::var(ENV_FREQUENCY)
+                .ok()
+                .and_then(|value| value.parse::<i32>().ok())
+                .unwrap_or(1000);
+
+            EnvProfileConfig {
+                output,
+                profile_once,
+                frequency,
+            }
+        })
+    }
+
+    struct ProfileState {
+        guard: Option<pprof::ProfilerGuard<'static>>,
+        output: Option<PathBuf>,
+    }
+
+    fn state() -> &'static Mutex<ProfileState> {
+        static STATE: OnceLock<Mutex<ProfileState>> = OnceLock::new();
+        STATE.get_or_init(|| {
+            Mutex::new(ProfileState {
+                guard: None,
+                output: None,
+            })
+        })
+    }
+
+    pub fn start(output_path: PathBuf, frequency: i32) -> Result<()> {
+        let mut state = state()
+            .lock()
+            .map_err(|_| ConversionError::Other("profiling state lock poisoned".to_string()))?;
+
+        if state.guard.is_some() {
+            return Err(ConversionError::Other("profiling already active".to_string()));
+        }
+
+        let guard = pprof::ProfilerGuardBuilder::default()
+            .frequency(frequency)
+            .blocklist(&["libc", "libpthread", "libgcc", "libm"])
+            .build()
+            .map_err(|err| ConversionError::Other(format!("Profiling init failed: {err}")))?;
+
+        state.guard = Some(guard);
+        state.output = Some(output_path);
+        PROFILE_ACTIVE.store(true, Ordering::Release);
+        Ok(())
+    }
+
+    pub fn stop() -> Result<()> {
+        let (guard, output) = {
+            let mut state = state()
+                .lock()
+                .map_err(|_| ConversionError::Other("profiling state lock poisoned".to_string()))?;
+            let guard = state.guard.take();
+            let output = state.output.take();
+            (guard, output)
+        };
+        PROFILE_ACTIVE.store(false, Ordering::Release);
+
+        let Some(guard) = guard else {
+            return Err(ConversionError::Other("profiling not active".to_string()));
+        };
+        let Some(output_path) = output else {
+            return Err(ConversionError::Other("profiling output path missing".to_string()));
+        };
+
+        if let Some(parent) = output_path.parent() {
+            std::fs::create_dir_all(parent).map_err(ConversionError::IoError)?;
+        }
+
+        let report = guard
+            .report()
+            .build()
+            .map_err(|err| ConversionError::Other(format!("Profiling report failed: {err}")))?;
+
+        let file = std::fs::File::create(&output_path).map_err(ConversionError::IoError)?;
+        report
+            .flamegraph(file)
+            .map_err(|err| ConversionError::Other(format!("Flamegraph write failed: {err}")))?;
+        PROFILE_ACTIVE.store(false, Ordering::Release);
+        Ok(())
+    }
+
+    pub fn maybe_profile<T, F>(f: F) -> Result<T>
+    where
+        F: FnOnce() -> Result<T>,
+    {
+        if PROFILE_ACTIVE.load(Ordering::Relaxed) {
+            return f();
+        }
+
+        let config = env_profile_config();
+        let Some(output_path) = config.output.as_ref() else {
+            return f();
+        };
+
+        if config.profile_once && PROFILED_ONCE.swap(true, Ordering::SeqCst) {
+            return f();
+        }
+
+        struct ActiveGuard;
+        impl Drop for ActiveGuard {
+            fn drop(&mut self) {
+                PROFILE_ACTIVE.store(false, Ordering::Release);
+            }
+        }
+        PROFILE_ACTIVE.store(true, Ordering::Release);
+        let _active = ActiveGuard;
+
+        let guard = pprof::ProfilerGuardBuilder::default()
+            .frequency(config.frequency)
+            .blocklist(&["libc", "libpthread", "libgcc", "libm"])
+            .build()
+            .map_err(|err| ConversionError::Other(format!("Profiling init failed: {err}")))?;
+
+        let result = f();
+
+        if result.is_ok() {
+            if let Some(parent) = output_path.parent() {
+                std::fs::create_dir_all(parent).map_err(ConversionError::IoError)?;
+            }
+
+            let report = guard
+                .report()
+                .build()
+                .map_err(|err| ConversionError::Other(format!("Profiling report failed: {err}")))?;
+
+            let file = std::fs::File::create(output_path).map_err(ConversionError::IoError)?;
+            report
+                .flamegraph(file)
+                .map_err(|err| ConversionError::Other(format!("Flamegraph write failed: {err}")))?;
+        }
+
+        result
+    }
+}
+
+#[cfg(all(not(target_os = "windows"), feature = "profiling"))]
+pub use enabled::{maybe_profile, start, stop};
+
+#[cfg(target_os = "windows")]
+pub fn start(_output_path: PathBuf, _frequency: i32) -> Result<()> {
+    Err(ConversionError::Other(
+        "Profiling is not supported on Windows".to_string(),
+    ))
+}
+
+#[cfg(all(not(target_os = "windows"), not(feature = "profiling")))]
+pub fn start(_output_path: PathBuf, _frequency: i32) -> Result<()> {
+    Err(ConversionError::Other(
+        "Profiling is disabled; rebuild with the profiling feature".to_string(),
+    ))
+}
+
+#[cfg(target_os = "windows")]
+pub fn stop() -> Result<()> {
+    Err(ConversionError::Other(
+        "Profiling is not supported on Windows".to_string(),
+    ))
+}
+
+#[cfg(all(not(target_os = "windows"), not(feature = "profiling")))]
+pub fn stop() -> Result<()> {
+    Err(ConversionError::Other(
+        "Profiling is disabled; rebuild with the profiling feature".to_string(),
+    ))
+}
+
+#[cfg(any(target_os = "windows", not(feature = "profiling")))]
+pub fn maybe_profile<T, F>(f: F) -> Result<T>
+where
+    F: FnOnce() -> Result<T>,
+{
+    f()
+}

data/lib/html_to_markdown/version.rb

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

data/lib/html_to_markdown.rb

@@ -12,9 +12,11 @@ module HtmlToMarkdown
   class << self
     alias native_convert convert
     alias native_convert_with_inline_images convert_with_inline_images
+    alias native_convert_with_inline_images_handle convert_with_inline_images_handle
     alias native_options options
     alias native_convert_with_options convert_with_options
     alias native_convert_with_metadata convert_with_metadata
+    alias native_convert_with_metadata_handle convert_with_metadata_handle
   end
 
   module_function
@@ -31,6 +33,10 @@ module HtmlToMarkdown
     native_convert_with_inline_images(html.to_s, options, image_config)
   end
 
+  def convert_with_inline_images_handle(html, options_handle, image_config = nil)
+    native_convert_with_inline_images_handle(html.to_s, options_handle, image_config)
+  end
+
   def options(options_hash = nil)
     native_options(options_hash)
   end
@@ -160,4 +166,8 @@ module HtmlToMarkdown
   def convert_with_metadata(html, options = nil, metadata_config = nil)
     native_convert_with_metadata(html.to_s, options, metadata_config)
   end
+
+  def convert_with_metadata_handle(html, options_handle, metadata_config = nil)
+    native_convert_with_metadata_handle(html.to_s, options_handle, metadata_config)
+  end
 end

data/sig/html_to_markdown.rbs

@@ -162,11 +162,21 @@ module HtmlToMarkdown
   def self.native_convert: (String html, conversion_options? options) -> String
   def self.native_options: (conversion_options? options_hash) -> Options
   def self.native_convert_with_options: (String html, Options options_handle) -> String
+  def self.native_convert_with_inline_images_handle: (
+    String html,
+    Options options_handle,
+    inline_image_config? image_config
+  ) -> html_extraction
   def self.native_convert_with_inline_images: (
     String html,
     conversion_options? options,
     inline_image_config? image_config
   ) -> html_extraction
+  def self.native_convert_with_metadata_handle: (
+    String html,
+    Options options_handle,
+    metadata_config? metadata_config
+  ) -> [String, extended_metadata]
   def self.native_convert_with_metadata: (
     String html,
     conversion_options? options,
@@ -176,11 +186,21 @@ module HtmlToMarkdown
   def native_convert: (String html, conversion_options? options) -> String
   def native_options: (conversion_options? options_hash) -> Options
   def native_convert_with_options: (String html, Options options_handle) -> String
+  def native_convert_with_inline_images_handle: (
+    String html,
+    Options options_handle,
+    inline_image_config? image_config
+  ) -> html_extraction
   def native_convert_with_inline_images: (
     String html,
     conversion_options? options,
     inline_image_config? image_config
   ) -> html_extraction
+  def native_convert_with_metadata_handle: (
+    String html,
+    Options options_handle,
+    metadata_config? metadata_config
+  ) -> [String, extended_metadata]
   def native_convert_with_metadata: (
     String html,
     conversion_options? options,
@@ -197,6 +217,11 @@ module HtmlToMarkdown
 
   # Convert HTML using a pre-built options handle
   def self.convert_with_options: (String html, Options options_handle) -> String
+  def self.convert_with_inline_images_handle: (
+    String html,
+    Options options_handle,
+    ?inline_image_config image_config
+  ) -> html_extraction
 
   # Convert HTML with inline image extraction
   def self.convert_with_inline_images: (
@@ -236,11 +261,21 @@ module HtmlToMarkdown
     ?conversion_options options,
     ?metadata_config metadata_config
   ) -> [String, extended_metadata]
+  def self.convert_with_metadata_handle: (
+    String html,
+    Options options_handle,
+    ?metadata_config metadata_config
+  ) -> [String, extended_metadata]
 
   # Instance method versions (created by module_function)
   def convert: (String html, ?conversion_options options) -> String
   def options: (?conversion_options options_hash) -> Options
   def convert_with_options: (String html, Options options_handle) -> String
+  def convert_with_inline_images_handle: (
+    String html,
+    Options options_handle,
+    ?inline_image_config image_config
+  ) -> html_extraction
   def convert_with_inline_images: (
     String html,
     ?conversion_options options,
@@ -251,4 +286,9 @@ module HtmlToMarkdown
     ?conversion_options options,
     ?metadata_config metadata_config
   ) -> [String, extended_metadata]
+  def convert_with_metadata_handle: (
+    String html,
+    Options options_handle,
+    ?metadata_config metadata_config
+  ) -> [String, extended_metadata]
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: html-to-markdown
 version: !ruby/object:Gem::Version
-  version: 2.15.0
+  version: 2.16.0
 platform: ruby
 authors:
 - Na'aman Hirschfeld
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-19 00:00:00.000000000 Z
+date: 2025-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -56,6 +56,7 @@ files:
 - ext/html-to-markdown-rb/native/README.md
 - ext/html-to-markdown-rb/native/extconf.rb
 - ext/html-to-markdown-rb/native/src/lib.rs
+- ext/html-to-markdown-rb/native/src/profiling.rs
 - html-to-markdown-rb.gemspec
 - lib/html_to_markdown.rb
 - lib/html_to_markdown/cli.rb