fix(links): support mailto: and tel: links in HTML and DOCX conversion (#2644)

Author: udbhav-shrinet

packages/markitdown/src/markitdown/converters/_markdownify.py

@@ -71,19 +71,27 @@ def convert_a(
         href = el.get("href")
         title = el.get("title")
 
-        # Escape URIs and skip non-http or file schemes
+        # Escape URIs and skip non-http or file schemes.
+        # mailto: and tel: links are kept because they are common in
+        # documents and do not execute code.
+        _SAFE_SCHEMES = {"http", "https", "file", "mailto", "tel"}
         if href:
             try:
                 parsed_url = urlparse(href)  # type: ignore
-                if parsed_url.scheme and parsed_url.scheme.lower() not in ["http", "https", "file"]:  # type: ignore
+                if parsed_url.scheme and parsed_url.scheme.lower() not in _SAFE_SCHEMES:  # type: ignore
                     return "%s%s%s" % (prefix, text, suffix)
-                href = urlunparse(
-                    parsed_url._replace(
-                        path=_quote_path_preserving_percent_encoded_octets(
-                            parsed_url.path
+                # mailto: and tel: URIs have no hierarchical path to
+                # percent-encode, so pass them through unchanged.
+                if parsed_url.scheme and parsed_url.scheme.lower() in {"mailto", "tel"}:
+                    pass  # keep href as-is
+                else:
+                    href = urlunparse(
+                        parsed_url._replace(
+                            path=_quote_path_preserving_percent_encoded_octets(
+                                parsed_url.path
+                            )
                         )
-                    )
-                )  # type: ignore
+                    )  # type: ignore
             except ValueError:  # It's not clear if this ever gets thrown
                 return "%s%s%s" % (prefix, text, suffix)
 

packages/markitdown/tests/test_html.py

@@ -101,6 +101,16 @@ def test_html_href_does_not_quote_query_or_fragment() -> None:
     assert f"[example]({expected_href})" in markdown
 
 
+def test_html_href_preserves_mailto_and_tel_links() -> None:
+    html = (
+        '<p>Contact <a href="mailto:team@example.com">the team</a> or '
+        '<a href="tel:+1234567890">call us</a>.</p>'
+    )
+    markdown = _convert_html(html)
+    assert "[the team](mailto:team@example.com)" in markdown
+    assert "[call us](tel:+1234567890)" in markdown
+
+
 def test_img_prefers_data_src_over_placeholder_data_uri() -> None:
     placeholder = (
         "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBTAA7"