tomd

Convert HTML to Markdown.

tomd is a small Python library that takes an HTML string and returns the Markdown that produced it (or an approximation, when the HTML wasn't originally Markdown). Handy for archiving articles, scraped blog posts, or anything else where you'd rather work with plain text than DOM trees.

Install

pip install tomd

Requires Python 3.10+.

Quickstart

import tomd

tomd.convert("<h1>Hello, world!</h1>")
# => '\n# Hello, world!\n'

Or via the class:

from tomd import Tomd

Tomd("<h1>Hello, world!</h1>").markdown

What it supports

If your HTML can't be cleanly expressed in Markdown (nested layouts, floating divs, etc.), the output will lose some structure — tomd aims at the round-trip Markdown → HTML → Markdown case, not arbitrary HTML.

Example

from tomd import Tomd

html = """
<h1>Heading</h1>
<p><b>bold</b> and <i>italic</i> and <a href="https://example.com">a link</a></p>
<ul>
  <li>one</li>
  <li>two</li>
</ul>
<blockquote>a quote</blockquote>
"""

print(Tomd(html).markdown)

# Heading

**bold** and *italic* and [a link](https://example.com)

- one
- two

> a quote

Development

git clone https://github.com/elliotgao2/tomd.git
cd tomd
uv sync             # install deps into .venv
uv run pytest       # run tests
uv run ruff check . # lint

We use uv for packaging and ruff for lint + format. Install the pre-commit hooks:

uv run pre-commit install

Roadmap

• Headings, emphasis, links, images, lists, blockquotes, tables, HR, code blocks
• Nested lists
• CLI (tomd < input.html > output.md)

Contributing

Pull requests are welcome. For non-trivial changes, please open an issue first to discuss. Make sure uv run pytest and uv run ruff check . pass before submitting.

License

MIT © Elliot Gao