mdread

Fetch any public URL as clean Markdown.

Agent-friendly HTML→Markdown with redirect re-validation and size limits. Extracted from tomo's web_fetch tool.

pip install mdread
# or with uv:
uv add mdread
# or as a CLI tool:
uv tool install mdread

Why mdread?

Quick start

from mdread import fetch, html_to_markdown, HtmlToMarkdown

# Fetch a page as Markdown
md = fetch("https://example.com")
print(md)

# Convert HTML you already have
print(html_to_markdown("<h1>Hi</h1><p>Hello <strong>world</strong>.</p>"))
# → # Hi
#   Hello **world**.

# Full CommonMark converter (options: ATX headings, fenced code, …)
converter = HtmlToMarkdown({"headingStyle": "atx", "codeBlockStyle": "fenced"})
print(converter.convert("<h2>Title</h2><ul><li>One</li></ul>"))

Structured result

from mdread import fetch_result, FetchError

result = fetch_result("https://example.com", raise_on_error=True)
print(result.url, result.truncated, len(result.text))

CLI

mdread https://example.com
mdread --timeout 30 --max-chars 50000 https://docs.python.org/3/
python -m mdread https://example.com

API

On soft failure (default), fetch returns a string starting with Error: so agent tool loops never crash.

Safety defaults

• Only http / https
• Manual redirect following (each hop re-checked), max 5 redirects
• Default 15s timeout, 100k char output cap

Install / develop

git clone https://github.com/Alg0rix/mdread
cd mdread
uv sync --group dev   # or: pip install -e ".[dev]"
pytest

License

MIT