html-to-markdown 2.29.0-arm64-darwin

data/Steepfile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Steepfile for type checking html-to-markdown Ruby gem
+
+target :lib do
+  signature 'sig'
+
+  check 'lib'
+
+  # Configure libraries
+  library 'pathname'
+  library 'open3'
+
+  # Ignore vendor directory
+  ignore 'vendor'
+
+  # Ignore spec directory
+  ignore 'spec'
+
+  # Ignore bin directory
+  ignore 'bin'
+
+  # Ignore internal implementation modules (not public API)
+  ignore 'lib/html_to_markdown/cli.rb'
+  ignore 'lib/html_to_markdown/cli_proxy.rb'
+end

data/bin/benchmark.rb

@@ -0,0 +1,232 @@
+#!/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',
+  scenario: 'convert-default',
+  visitor: nil
+}
+
+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('--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
+
+  parser.on('--visitor VISITOR', 'Visitor type (noop, simple, custom, complex)') do |visitor|
+    options[:visitor] = visitor if %w[noop simple custom complex].include?(visitor)
+  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
+
+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
+
+# Visitor factory functions
+def create_noop_visitor
+  {
+    visit_text: proc { |_ctx, _text| 'continue' },
+    visit_heading: proc { |_ctx, _level, _text, _id| 'continue' },
+    visit_paragraph: proc { |_ctx, _text| 'continue' },
+    visit_link: proc { |_ctx, _href, _text, _title| 'continue' },
+    visit_image: proc { |_ctx, _src, _alt, _title| 'continue' },
+    visit_strong: proc { |_ctx, _text| 'continue' },
+    visit_em: proc { |_ctx, _text| 'continue' },
+    visit_code: proc { |_ctx, _text| 'continue' },
+    visit_br: proc { |_ctx| 'continue' }
+  }
+end
+
+def create_simple_visitor
+  {
+    text_count: 0,
+    link_count: 0,
+    image_count: 0,
+    visit_text: proc { |_ctx, _text| 'continue' },
+    visit_heading: proc { |_ctx, _level, _text, _id| 'continue' },
+    visit_paragraph: proc { |_ctx, _text| 'continue' },
+    visit_link: proc { |_ctx, _href, _text, _title| 'continue' },
+    visit_image: proc { |_ctx, _src, _alt, _title| 'continue' },
+    visit_strong: proc { |_ctx, _text| 'continue' },
+    visit_em: proc { |_ctx, _text| 'continue' },
+    visit_code: proc { |_ctx, _text| 'continue' },
+    visit_br: proc { |_ctx| 'continue' }
+  }
+end
+
+def create_custom_visitor
+  {
+    visit_text: proc { |_ctx, _text| 'continue' },
+    visit_heading: proc { |_ctx, _level, _text, _id| 'continue' },
+    visit_paragraph: proc { |_ctx, _text| 'continue' },
+    visit_link: proc { |_ctx, href, text, _title| ['custom', "LINK[#{text}](#{href})"] },
+    visit_image: proc { |_ctx, src, alt, _title| ['custom', "![#{alt}](#{src})"] },
+    visit_strong: proc { |_ctx, _text| 'continue' },
+    visit_em: proc { |_ctx, _text| 'continue' },
+    visit_code: proc { |_ctx, _text| 'continue' },
+    visit_br: proc { |_ctx| 'continue' }
+  }
+end
+
+def create_complex_visitor
+  {
+    texts: 0,
+    links: 0,
+    images: 0,
+    headings: 0,
+    visit_text: proc { |_ctx, _text| 'continue' },
+    visit_heading: proc { |_ctx, _level, _text, _id| 'continue' },
+    visit_paragraph: proc { |_ctx, _text| 'continue' },
+    visit_link: proc { |_ctx, href, text, _title| ['custom', "[#{text}](#{href})"] },
+    visit_image: proc { |_ctx, _src, _alt, _title| 'skip' },
+    visit_strong: proc { |_ctx, _text| 'continue' },
+    visit_em: proc { |_ctx, _text| 'continue' },
+    visit_code: proc { |_ctx, _text| 'continue' },
+    visit_br: proc { |_ctx| 'continue' }
+  }
+end
+
+html = File.binread(fixture)
+html.force_encoding(Encoding::UTF_8)
+html.freeze
+iterations = options[:iterations]
+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
+
+# Create visitor if specified
+visitor = nil
+if options[:visitor]
+  visitor_creators = {
+    'noop' => method(:create_noop_visitor),
+    'simple' => method(:create_simple_visitor),
+    'custom' => method(:create_custom_visitor),
+    'complex' => method(:create_complex_visitor)
+  }
+  creator = visitor_creators[options[:visitor]]
+  visitor = creator.call if creator
+end
+
+SCENARIO_RUNNERS = {
+  'convert-default' => ->(html, _options, _handle, _visitor) { HtmlToMarkdown.convert(html) },
+  'convert-options' => lambda do |html, _options, handle, _visitor|
+    raise ArgumentError, 'options handle required' unless handle
+
+    HtmlToMarkdown.convert_with_options(html, handle)
+  end,
+  'inline-images-default' => lambda { |html, _options, _handle, _visitor|
+    HtmlToMarkdown.convert_with_inline_images(html, nil, nil)
+  },
+  'inline-images-options' => lambda do |html, _options, handle, _visitor|
+    raise ArgumentError, 'options handle required' unless handle
+
+    HtmlToMarkdown.convert_with_inline_images_handle(html, handle, nil)
+  end,
+  'metadata-default' => ->(html, _options, _handle, _visitor) { HtmlToMarkdown.convert_with_metadata(html, nil, nil) },
+  'metadata-options' => lambda do |html, _options, handle, _visitor|
+    raise ArgumentError, 'options handle required' unless handle
+
+    HtmlToMarkdown.convert_with_metadata_handle(html, handle, nil)
+  end
+}.freeze
+
+def run_scenario(html, scenario, options, handle, visitor = nil)
+  if visitor
+    HtmlToMarkdown.convert_with_visitor(html, nil, visitor)
+  else
+    runner = SCENARIO_RUNNERS.fetch(scenario) { raise ArgumentError, "Unsupported scenario: #{scenario}" }
+    runner.call(html, options, handle, visitor)
+  end
+end
+
+run_scenario(html, options[:scenario], conversion_options, options_handle, visitor)
+
+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 { run_scenario(html, options[:scenario], conversion_options, options_handle, visitor) }
+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
+mb_per_sec = (bytes_processed.to_f / (1024 * 1024)) / elapsed
+
+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)},
+  "mb_per_sec":#{format('%.4f', mb_per_sec)},
+  "bytes_processed":#{bytes_processed},
+  "payload_size_bytes":#{payload_size_bytes}
+})
+
+puts payload.strip

data/exe/html-to-markdown

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'html_to_markdown/cli'
+
+exit HtmlToMarkdown::CLI.run(ARGV)

data/html-to-markdown-rb.gemspec

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative 'lib/html_to_markdown/version'
+
+repo_root = File.expand_path('../..', __dir__)
+crate_prefix = 'packages/ruby/'
+git_cmd = %(git -C "#{repo_root}" ls-files -z #{crate_prefix})
+ruby_files =
+  `#{git_cmd}`.split("\x0")
+              .select { |path| path.start_with?(crate_prefix) }
+              .map { |path| path.delete_prefix(crate_prefix) }
+
+fallback_files = Dir.chdir(__dir__) do
+  Dir.glob(
+    %w[
+      README.md
+      ext/**/*
+      exe/*
+      lib/**/*.rb
+      lib/bin/*
+      src/**/*.rs
+      spec/**/*.rb
+      sig/**/*.rbs
+    ]
+  )
+end
+
+# Vendor files: include vendored crates and workspace Cargo.toml
+vendor_files = Dir.chdir(__dir__) do
+  Dir.glob('vendor/html-to-markdown-rs/**/*', File::FNM_DOTMATCH)
+     .select { |f| File.file?(f) }
+     .grep_v(%r{/target/})
+     .grep_v(/\.(swp|bak|tmp)$/)
+end
+
+# Include vendor/Cargo.toml (workspace definition) if it exists
+workspace_toml = if File.exist?(File.join(__dir__, 'vendor/Cargo.toml'))
+                   ['vendor/Cargo.toml']
+                 else
+                   []
+                 end
+
+# When vendor exists, use ext/ files from filesystem (modified by vendor script)
+# instead of git (which has the unmodified Cargo.toml with workspace paths)
+ext_files_from_fs = Dir.chdir(__dir__) do
+  Dir.glob('ext/**/*', File::FNM_DOTMATCH)
+     .reject { |f| File.directory?(f) }
+     .reject { |f| f.include?('/target/') }
+end
+
+# Include native artifacts (.so, .bundle, .dylib) if present (for platform gems)
+native_files = Dir.chdir(__dir__) do
+  Dir.glob('lib/**/*.{so,bundle,dylib}')
+end
+
+files = if vendor_files.any?
+          # Vendor exists: use ext/ from filesystem (has modified Cargo.toml)
+          non_ext_ruby_files = (ruby_files.empty? ? fallback_files : ruby_files)
+                               .reject { |f| f.start_with?('ext/') }
+          non_ext_ruby_files + ext_files_from_fs + vendor_files + workspace_toml + native_files
+        else
+          ruby_files.empty? ? fallback_files : ruby_files
+        end
+
+files = files.uniq
+
+Gem::Specification.new do |spec|
+  spec.name          = 'html-to-markdown'
+  spec.version       = HtmlToMarkdown::VERSION
+  spec.authors       = ["Na'aman Hirschfeld"]
+  spec.email         = ['nhirschfeld@gmail.com']
+
+  spec.summary       = 'Blazing-fast HTML to Markdown conversion for Ruby, powered by Rust.'
+  spec.description   = <<~DESC.strip
+    html-to-markdown is a native Ruby extension built on the shared Rust engine that powers the html-to-markdown project.
+    It delivers identical HTML-to-Markdown output across languages, exposes inline image extraction, and ships with a CLI for automation workflows.
+  DESC
+  spec.homepage      = 'https://github.com/kreuzberg-dev/html-to-markdown'
+  spec.license       = 'MIT'
+
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.2')
+
+  spec.bindir = 'exe'
+  spec.executables = ['html-to-markdown']
+  spec.require_paths = ['lib']
+
+  spec.files = files
+  spec.extra_rdoc_files = ['README.md']
+
+  spec.extensions = ['ext/html-to-markdown-rb/extconf.rb']
+
+  spec.add_dependency 'rb_sys', '>= 0.9', '< 1.0'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata['homepage_uri'] = 'https://github.com/kreuzberg-dev/html-to-markdown'
+  spec.metadata['source_code_uri'] = 'https://github.com/kreuzberg-dev/html-to-markdown'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/kreuzberg-dev/html-to-markdown/issues'
+  spec.metadata['changelog_uri'] = 'https://github.com/kreuzberg-dev/html-to-markdown/releases'
+  spec.metadata['documentation_uri'] = 'https://github.com/kreuzberg-dev/html-to-markdown/blob/main/packages/ruby/README.md'
+end

data/lib/html_to_markdown/cli.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'html_to_markdown/cli_proxy'
+
+module HtmlToMarkdown
+  module CLI
+    module_function
+
+    def run(argv = ARGV, stdout: $stdout, stderr: $stderr)
+      output = CLIProxy.call(argv)
+      stdout.print(output)
+      0
+    rescue CLIProxy::CLIExecutionError => e
+      stderr.print(e.stderr)
+      e.status || 1
+    rescue CLIProxy::MissingBinaryError, CLIProxy::Error => e
+      stderr.puts(e.message)
+      1
+    end
+  end
+end

data/lib/html_to_markdown/cli_proxy.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'pathname'
+
+module HtmlToMarkdown
+  module CLIProxy
+    class Error < StandardError
+    end
+
+    class MissingBinaryError < Error
+    end
+
+    class CLIExecutionError < Error
+      attr_reader :stderr, :status
+
+      def initialize(message, stderr:, status:)
+        super(message)
+        @stderr = stderr
+        @status = status
+      end
+    end
+
+    module_function
+
+    def call(argv)
+      binary = find_cli_binary
+      args = Array(argv).map(&:to_s)
+      stdout, stderr, status = Open3.capture3(binary.to_s, *args)
+      return stdout if status.success?
+
+      raise CLIExecutionError.new(
+        "html-to-markdown CLI exited with status #{status.exitstatus}",
+        stderr: stderr,
+        status: status.exitstatus
+      )
+    end
+
+    def find_cli_binary
+      binary_name = Gem.win_platform? ? 'html-to-markdown.exe' : 'html-to-markdown'
+      found = search_paths(binary_name).find(&:file?)
+      return found if found
+
+      raise MissingBinaryError, missing_binary_message
+    end
+
+    def root_path
+      @root_path ||= Pathname(__dir__.to_s).join('../..').expand_path
+    end
+
+    def lib_path
+      @lib_path ||= Pathname(__dir__.to_s).join('..').expand_path
+    end
+
+    def search_paths(binary_name)
+      paths = [
+        root_path.join('target', 'release', binary_name),
+        lib_path.join('bin', binary_name),
+        lib_path.join(binary_name)
+      ]
+
+      workspace_root = root_path.parent&.parent
+      paths << workspace_root.join('target', 'release', binary_name) if workspace_root
+      paths
+    end
+
+    def missing_binary_message
+      <<~MSG.strip
+        html-to-markdown CLI binary not found. Build it with
+        `cargo build --release --package html-to-markdown-cli`.
+      MSG
+    end
+  end
+end

data/lib/html_to_markdown/version.rb

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

data/lib/html_to_markdown.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require_relative 'html_to_markdown/version'
+require 'html_to_markdown_rb'
+
+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_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
+    alias native_convert_with_visitor convert_with_visitor
+    alias native_convert_with_tables convert_with_tables
+  end
+
+  module_function
+
+  def convert(html, options = nil, visitor = nil)
+    if visitor
+      native_convert_with_visitor(html.to_s, options, visitor)
+    else
+      native_convert(html.to_s, options)
+    end
+  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, _visitor = nil)
+    # NOTE: visitor parameter is accepted for API compatibility but not used in inline images mode
+    # The visitor pattern is only supported in the standard convert() method
+    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
+
+  # Convert HTML to Markdown with comprehensive metadata extraction.
+  #
+  # Performs HTML-to-Markdown conversion while extracting document metadata, headers,
+  # links, images, and structured data in a single pass. Ideal for content analysis,
+  # SEO workflows, and document indexing.
+  #
+  # @param html [String] HTML string to convert. Line endings are normalized (CRLF -> LF).
+  # @param options [ConversionOptions, Hash, nil] Optional conversion configuration.
+  #   When a Hash, keys should match ConversionOptions field names (as symbols or strings).
+  #   Common options:
+  #   - :heading_style [String] "atx", "atx_closed", or "underlined" (default: "underlined")
+  #   - :list_indent_type [String] "spaces" or "tabs" (default: "spaces")
+  #   - :list_indent_width [Integer] Spaces per indent level (default: 4)
+  #   - :wrap [true, false] Enable text wrapping (default: false)
+  #   - :wrap_width [Integer] Wrap at this column width (default: 80)
+  #   See ConversionOptions documentation for complete list.
+  #
+  # @param metadata_config [Hash, nil] Optional metadata extraction configuration.
+  #   Keys should be symbols or strings. Supported keys:
+  #   - :extract_headers [true, false] Extract h1-h6 heading elements (default: true)
+  #   - :extract_links [true, false] Extract hyperlinks with type classification (default: true)
+  #   - :extract_images [true, false] Extract image elements (default: true)
+  #   - :extract_structured_data [true, false] Extract JSON-LD/Microdata/RDFa (default: true)
+  #   - :max_structured_data_size [Integer] Size limit for structured data in bytes (default: 1_000_000)
+  #
+  # @return [Array<String, Hash>] Tuple of [markdown_string, metadata_hash]
+  #   markdown_string: String - The converted Markdown output
+  #
+  #   metadata_hash: Hash with keys:
+  #   - :document [Hash] Document-level metadata:
+  #     - :title [String, nil] From <title> tag
+  #     - :description [String, nil] From <meta name="description">
+  #     - :keywords [Array<String>] From <meta name="keywords">
+  #     - :author [String, nil] From <meta name="author">
+  #     - :language [String, nil] From lang attribute (e.g., "en")
+  #     - :text_direction [String, nil] "ltr", "rtl", or "auto"
+  #     - :canonical_url [String, nil] From <link rel="canonical">
+  #     - :base_href [String, nil] From <base href="">
+  #     - :open_graph [Hash<String, String>] Open Graph properties (og:* meta tags)
+  #     - :twitter_card [Hash<String, String>] Twitter Card properties (twitter:* meta tags)
+  #     - :meta_tags [Hash<String, String>] Other meta tags
+  #
+  #   - :headers [Array<Hash>] Heading elements:
+  #     - :level [Integer] 1-6
+  #     - :text [String] Header text content
+  #     - :id [String, nil] HTML id attribute
+  #     - :depth [Integer] Tree nesting depth
+  #     - :html_offset [Integer] Byte offset in original HTML
+  #
+  #   - :links [Array<Hash>] Hyperlinks:
+  #     - :href [String] Link URL
+  #     - :text [String] Link text content
+  #     - :title [String, nil] Title attribute
+  #     - :link_type [String] "anchor", "internal", "external", "email", "phone", or "other"
+  #     - :rel [Array<String>] Rel attribute values
+  #     - :attributes [Hash<String, String>] Additional HTML attributes
+  #
+  #   - :images [Array<Hash>] Image elements:
+  #     - :src [String] Image source URL or data URI
+  #     - :alt [String, nil] Alt text for accessibility
+  #     - :title [String, nil] Title attribute
+  #     - :dimensions [Array<Integer>, nil] [width, height] if available
+  #     - :image_type [String] "data_uri", "external", "relative", or "inline_svg"
+  #     - :attributes [Hash<String, String>] Additional HTML attributes
+  #
+  #   - :structured_data [Array<Hash>] Structured data blocks:
+  #     - :data_type [String] "json_ld", "microdata", or "rdfa"
+  #     - :raw_json [String] Raw JSON content
+  #     - :schema_type [String, nil] Schema type (e.g., "Article", "Event")
+  #
+  # @raise [StandardError] If conversion fails or invalid configuration
+  #
+  # @example Basic usage
+  #   html = <<~HTML
+  #     <html lang="en">
+  #       <head>
+  #         <title>My Article</title>
+  #         <meta name="description" content="A great read">
+  #       </head>
+  #       <body>
+  #         <h1 id="intro">Introduction</h1>
+  #         <p>Visit <a href="https://example.com">our site</a></p>
+  #         <img src="photo.jpg" alt="Beautiful landscape">
+  #       </body>
+  #     </html>
+  #   HTML
+  #
+  #   markdown, metadata = HtmlToMarkdown.convert_with_metadata(html)
+  #
+  #   puts metadata[:document][:title]  # => "My Article"
+  #   puts metadata[:document][:language]  # => "en"
+  #   puts metadata[:headers].length  # => 1
+  #   puts metadata[:headers][0][:text]  # => "Introduction"
+  #   puts metadata[:links].length  # => 1
+  #   puts metadata[:images].length  # => 1
+  #
+  # @example With selective metadata extraction
+  #   config = {
+  #     extract_headers: true,
+  #     extract_links: true,
+  #     extract_images: false,      # Skip images
+  #     extract_structured_data: false  # Skip structured data
+  #   }
+  #
+  #   markdown, metadata = HtmlToMarkdown.convert_with_metadata(html, nil, config)
+  #   puts metadata[:images].empty?  # => true (not extracted)
+  #
+  # @example With conversion options
+  #   options = {
+  #     heading_style: "atx",     # Use # H1, ## H2 style
+  #     wrap: true,
+  #     wrap_width: 80
+  #   }
+  #
+  #   config = { extract_headers: true }
+  #
+  #   markdown, metadata = HtmlToMarkdown.convert_with_metadata(html, options, config)
+  #   # Markdown uses ATX-style headings and wraps at 80 characters
+  #
+  # @see #convert Simple conversion without metadata
+  # @see #convert_with_inline_images Extract inline images during conversion
+  # @see ConversionOptions Detailed conversion configuration
+  def convert_with_metadata(html, options = nil, metadata_config = nil, _visitor = nil)
+    # NOTE: visitor parameter is accepted for API compatibility but not used in metadata extraction mode
+    # The visitor pattern is only supported in the standard convert() method
+    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
+
+  # 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