microsoft / microsoft/markitdown

HTML conversion loses the base URL for relative links and images

Open
#2,500 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
186k
Forks
13.7k
Avg merge
1d 4h
Merged PRs (30d)
49

Description

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:

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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in HtmlConverter and trace how the document URL and HTML base element are handled, then inspect MarkItDown.convert_response() and its StreamInfo URL. Add focused coverage for ordinary and lazy-loaded images, links, an explicit base element, and the no-source-URL case. Done means relative references resolve correctly without fetching or adding dependencies.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
content
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.