feat: add wrap_links option to render links as plain "text: href"

CHANGELOG.md

@@ -5,6 +5,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased](https://github.com/soundasleep/html2text_ruby/compare/v0.4.0...master)
+### Added
+- Add a `wrap_links:` option to `Html2Text.convert` and `Html2Text.new` (default `true`); when `false`, hyperlinks render as `text: href` instead of markdown-style `[text](href)`. Only affects `<a href>` links — images and named anchors keep their `[bracketed]` format ([#40](https://github.com/soundasleep/html2text_ruby/pull/40))
+
 ### Changed
 - Require Ruby 3.3+; CI now tests Ruby 3.3, 3.4 and 4.0 ([#42](https://github.com/soundasleep/html2text_ruby/pull/42))
 - Update development dependencies (rubocop 1.88, nokogiri 1.19 in the lockfile), removing the transitive `rexml` dependency ([#42](https://github.com/soundasleep/html2text_ruby/pull/42))

lib/html2text.rb

@@ -5,11 +5,12 @@
 class Html2Text
   attr_reader :doc
 
-  def initialize(doc)
+  def initialize(doc, wrap_links: true)
     @doc = doc
+    @wrap_links = wrap_links
   end
 
-  def self.convert(html)
+  def self.convert(html, wrap_links: true)
     html = html.to_s
 
     if office_document?(html)
@@ -27,7 +28,7 @@ def self.convert(html)
     html = fix_newlines(replace_entities(html))
     doc = Nokogiri::HTML(html)
 
-    new(doc).convert
+    new(doc, wrap_links: wrap_links).convert
   end
 
   def self.fix_newlines(text)
@@ -175,7 +176,7 @@ def suffix_whitespace(node)
   end
   # rubocop:enable Lint/DuplicateBranch
 
-  # links are returned in [text](link) format
+  # links are returned in [text](link) format, or "text: link" with wrap_links: false
   def wrap_link(node, output)
     href = node.attribute('href')
     name = node.attribute('name')
@@ -202,6 +203,8 @@ def wrap_link(node, output)
          href != "http://#{output}" && href != "https://#{output}"
         output = if output.empty?
                    href
+                 elsif !@wrap_links
+                   "#{output}: #{href}"
                  else
                    "[#{output}](#{href})"
                  end

spec/wrap_links_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Html2Text do
+  describe 'the wrap_links option' do
+    it 'defaults to wrapping links in [text](href) format' do
+      text = Html2Text.convert('<a href="https://example.com">Click Here!</a>')
+      expect(text).to eq('[Click Here!](https://example.com)')
+    end
+
+    it 'renders links as "text: href" with wrap_links: false' do
+      text = Html2Text.convert('<a href="https://example.com">Click Here!</a>', wrap_links: false)
+      expect(text).to eq('Click Here!: https://example.com')
+    end
+
+    it 'is also accepted by the initializer' do
+      doc = Nokogiri::HTML('<a href="https://example.com">Click Here!</a>')
+      expect(Html2Text.new(doc, wrap_links: false).convert).to eq('Click Here!: https://example.com')
+    end
+
+    it 'unwraps linked images' do
+      text = Html2Text.convert('<a href="http://x.com"><img src="i.png" alt="two"></a>', wrap_links: false)
+      expect(text).to eq('two: http://x.com')
+    end
+
+    it 'still renders links with no text as the bare href' do
+      text = Html2Text.convert('<a href="http://x.com"></a>', wrap_links: false)
+      expect(text).to eq('http://x.com')
+    end
+
+    it 'still renders links whose text equals the href as just the text' do
+      text = Html2Text.convert('<a href="http://example.com">http://example.com</a>', wrap_links: false)
+      expect(text).to eq('http://example.com')
+    end
+
+    it 'still renders mailto links matching their text as just the text' do
+      text = Html2Text.convert('<a href="mailto:a@b.com">a@b.com</a>', wrap_links: false)
+      expect(text).to eq('a@b.com')
+    end
+  end
+end