#2500·markitdown

HTML conversion loses the base URL for relative links and images

Author: pentaoaCreated Sep 15, 2026Updated Sep 15, 2026

HTML conversion keeps relative link and image addresses even when the document's source URL is known. Once the generated Markdown is saved elsewhere or passed to an LLM, those addresses no longer identify the original resources. An HTML <base href> is also ignored.

Reproduced on main at eb31b5c9453628def5e6758a27a8e3a87b4ab101, without network access:

python
from markitdown.converters import HtmlConverter

result = HtmlConverter().convert_string(
    '<base href="../assets/">'
    '<a href="guide.html">Guide</a><img src="chart.png" alt="Chart">',
    url="https://example.com/docs/page.html",
)
print(result.markdown)

Actual: [Guide](guide.html)![Chart](chart.png).

The destinations should be https://example.com/assets/guide.html and https://example.com/assets/chart.png. The same problem affects MarkItDown.convert_response(), which already supplies the final response URL in StreamInfo.

The HTML base-element rules use the first base element with an href, resolved against the document URL. I prepared a focused fix in HtmlConverter covering those rules, ordinary and lazy-loaded images, and the public response-conversion path. Without a source URL or an explicit base, relative references are left unchanged. No fetching or new dependency is needed.

AI assistance: OpenAI Codex.