markmaton

markmaton is a lightweight HTML-to-Markdown parser core built for agent workflows.

It solves the last-mile parsing problem in a web pipeline: you already have page HTML, but it is still too noisy and awkward for downstream agent use. Feed markmaton HTML from a fetcher or browser layer and get back cleaner Markdown, metadata, links, images, and quality signals.

[!NOTE] markmaton is a general parser, not a crawler. Feed it HTML from Playwright, fetch, Firecrawl, or another upstream page-visit tool.

Why it exists

Raw page HTML is usually not directly useful for downstream agent workflows.
Modern pages often mix the real content with navigation, overlays, cards, and app shell chrome.
markmaton keeps that cleanup and conversion step deterministic and separate from crawling.
The project stays narrow by design: no crawling, browser control, network, or LLM features.
The user-facing entrypoint is a Python CLI and API wrapped around a fast Go engine.

Install

`pip`

pip install markmaton

`uv tool`

uv tool install markmaton

[!TIP] The installed package works through plain pip. Local development uses uv with Python 3.12.

Quickstart

CLI

markmaton convert \
  --html-file page.html \
  --url https://example.com/article \
  --output-format markdown

To get the full structured response:

markmaton convert \
  --html-file page.html \
  --url https://example.com/article \
  --output-format json

Python API

from markmaton import ConvertOptions, ConvertRequest, convert_html

html = "<article><h1>Hello</h1><p>World</p></article>"

response = convert_html(
    ConvertRequest(
        html=html,
        url="https://example.com/article",
        options=ConvertOptions(only_main_content=True),
    )
)

print(response.markdown)
print(response.metadata.title)

[!TIP] Pass url whenever you can. markmaton uses it as parsing context for canonical metadata and absolute link resolution.

Output

JSON mode returns markdown, html_clean, metadata, links, images, and quality. See response shape for details.

Project shape

Go engine: cmd/markmaton-engine
Python wrapper and CLI: markmaton/
Parser fixtures and golden files: testdata/
Architecture, benchmark, and release docs: docs/

Documentation

Documentation index
Usage guide
Packaging layout
PyPI release path
Benchmark and regression workflow
Regression corpus
AI agent skill — for using markmaton inside an agent workflow

Development

Set up the local development environment:

uv sync --group dev

Run the core test suites:

uv run python -m unittest discover -s tests -p 'test_*.py'
go test ./...

For a manual end-to-end smoke:

Local smoke flow

The repo is pinned to:

Python 3.12 via .python-version
a committed uv.lock

[!IMPORTANT] Automated tests are unit-test-first. Live page visits and benchmarks are manual.

Release notes

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

markmaton-0.1.8.tar.gz (885.9 kB view details)

Uploaded Aug 3, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

markmaton-0.1.8-py3-none-win_amd64.whl (3.9 MB view details)

Uploaded Aug 3, 2026 Python 3Windows x86-64

markmaton-0.1.8-py3-none-manylinux2014_x86_64.whl (3.8 MB view details)

Uploaded Aug 3, 2026 Python 3

markmaton-0.1.8-py3-none-macosx_12_0_x86_64.whl (4.0 MB view details)

Uploaded Aug 3, 2026 Python 3macOS 12.0+ x86-64

markmaton-0.1.8-py3-none-macosx_12_0_arm64.whl (3.7 MB view details)

Uploaded Aug 3, 2026 Python 3macOS 12.0+ ARM64

File details

Details for the file markmaton-0.1.8.tar.gz.

File metadata

Download URL: markmaton-0.1.8.tar.gz
Upload date: Aug 3, 2026
Size: 885.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for markmaton-0.1.8.tar.gz
Algorithm	Hash digest
SHA256	`97338138c68de4a7e23ac7c9ab8c847e190ebacbb2bb5c9eb82453a74ad3e147`
MD5	`aac5ead4a52cfde5be4aab10cf7fe589`
BLAKE2b-256	`e6abf6475cce202b026d3680559c6fa9a0b7233208070cf3c1d85890e157fc6a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for markmaton-0.1.8.tar.gz:

Publisher: workflow.yml on appautomaton/markmaton

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: markmaton-0.1.8.tar.gz
- Subject digest: 97338138c68de4a7e23ac7c9ab8c847e190ebacbb2bb5c9eb82453a74ad3e147
- Sigstore transparency entry: 2336154812
- Sigstore integration time: Aug 3, 2026
Source repository:
- Permalink: appautomaton/markmaton@c0b21dac9ebd895c655e10036144b4cd8f73ec4c
- Branch / Tag: refs/tags/v0.1.8
- Owner: https://github.com/appautomaton
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: workflow.yml@c0b21dac9ebd895c655e10036144b4cd8f73ec4c
- Trigger Event: push

File details

Details for the file markmaton-0.1.8-py3-none-win_amd64.whl.

File metadata

Download URL: markmaton-0.1.8-py3-none-win_amd64.whl
Upload date: Aug 3, 2026
Size: 3.9 MB
Tags: Python 3, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for markmaton-0.1.8-py3-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`391c7807de01ad48fc046bd9c4997c1b2e3649c19b5bcbdc44b7413668b50d86`
MD5	`2cea29659d0e7386d03fc9f14f3f9ed8`
BLAKE2b-256	`a039d6d128a11d072b1969d887c6712f82c3e866625734a71ac196669d996fe9`

See more details on using hashes here.

Provenance

The following attestation bundles were made for markmaton-0.1.8-py3-none-win_amd64.whl:

Publisher: workflow.yml on appautomaton/markmaton

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: markmaton-0.1.8-py3-none-win_amd64.whl
- Subject digest: 391c7807de01ad48fc046bd9c4997c1b2e3649c19b5bcbdc44b7413668b50d86
- Sigstore transparency entry: 2336154829
- Sigstore integration time: Aug 3, 2026
Source repository:
- Permalink: appautomaton/markmaton@c0b21dac9ebd895c655e10036144b4cd8f73ec4c
- Branch / Tag: refs/tags/v0.1.8
- Owner: https://github.com/appautomaton
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: workflow.yml@c0b21dac9ebd895c655e10036144b4cd8f73ec4c
- Trigger Event: push

File details

Details for the file markmaton-0.1.8-py3-none-manylinux2014_x86_64.whl.

File metadata

Download URL: markmaton-0.1.8-py3-none-manylinux2014_x86_64.whl
Upload date: Aug 3, 2026
Size: 3.8 MB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for markmaton-0.1.8-py3-none-manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`5c7a22c23639600afc20c2ed430230fb2610a28897feaaf7f6b86f5fb61865f2`
MD5	`dab870d23c9c87297a53606acaf425e0`
BLAKE2b-256	`ff818568ec8076d1287966b8452105711dfc407550fbfcd8ae54be50f0c47deb`

See more details on using hashes here.

Provenance

The following attestation bundles were made for markmaton-0.1.8-py3-none-manylinux2014_x86_64.whl:

Publisher: workflow.yml on appautomaton/markmaton

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: markmaton-0.1.8-py3-none-manylinux2014_x86_64.whl
- Subject digest: 5c7a22c23639600afc20c2ed430230fb2610a28897feaaf7f6b86f5fb61865f2
- Sigstore transparency entry: 2336154828
- Sigstore integration time: Aug 3, 2026
Source repository:
- Permalink: appautomaton/markmaton@c0b21dac9ebd895c655e10036144b4cd8f73ec4c
- Branch / Tag: refs/tags/v0.1.8
- Owner: https://github.com/appautomaton
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: workflow.yml@c0b21dac9ebd895c655e10036144b4cd8f73ec4c
- Trigger Event: push

File details

Details for the file markmaton-0.1.8-py3-none-macosx_12_0_x86_64.whl.

File metadata

Download URL: markmaton-0.1.8-py3-none-macosx_12_0_x86_64.whl
Upload date: Aug 3, 2026
Size: 4.0 MB
Tags: Python 3, macOS 12.0+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for markmaton-0.1.8-py3-none-macosx_12_0_x86_64.whl
Algorithm	Hash digest
SHA256	`386abb1eef8b47b513b3bd0726971e66be9489c23ed697de04a00df00a58e220`
MD5	`3add57971d109e7947c6edede535f7ef`
BLAKE2b-256	`a6ecb1f5d5050829bea3c32de32d6e2003292ce484f7c2dd7e60c7db1cf1ad66`

See more details on using hashes here.

Provenance

The following attestation bundles were made for markmaton-0.1.8-py3-none-macosx_12_0_x86_64.whl:

Publisher: workflow.yml on appautomaton/markmaton

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: markmaton-0.1.8-py3-none-macosx_12_0_x86_64.whl
- Subject digest: 386abb1eef8b47b513b3bd0726971e66be9489c23ed697de04a00df00a58e220
- Sigstore transparency entry: 2336154821
- Sigstore integration time: Aug 3, 2026
Source repository:
- Permalink: appautomaton/markmaton@c0b21dac9ebd895c655e10036144b4cd8f73ec4c
- Branch / Tag: refs/tags/v0.1.8
- Owner: https://github.com/appautomaton
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: workflow.yml@c0b21dac9ebd895c655e10036144b4cd8f73ec4c
- Trigger Event: push

File details

Details for the file markmaton-0.1.8-py3-none-macosx_12_0_arm64.whl.

File metadata

Download URL: markmaton-0.1.8-py3-none-macosx_12_0_arm64.whl
Upload date: Aug 3, 2026
Size: 3.7 MB
Tags: Python 3, macOS 12.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for markmaton-0.1.8-py3-none-macosx_12_0_arm64.whl
Algorithm	Hash digest
SHA256	`8b22f257beb573ee889cc0d5fb521b200c67e65e86d6763cf3d9431e19a5fac6`
MD5	`8cc992a93b47b84675869b10c9fcff5f`
BLAKE2b-256	`03763318342c8b7bf0f2f0bff1c15c3a80bd2bf72bb03c9a9d844a89a14e7dcd`

See more details on using hashes here.

Provenance

The following attestation bundles were made for markmaton-0.1.8-py3-none-macosx_12_0_arm64.whl:

Publisher: workflow.yml on appautomaton/markmaton

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: markmaton-0.1.8-py3-none-macosx_12_0_arm64.whl
- Subject digest: 8b22f257beb573ee889cc0d5fb521b200c67e65e86d6763cf3d9431e19a5fac6
- Sigstore transparency entry: 2336154833
- Sigstore integration time: Aug 3, 2026
Source repository:
- Permalink: appautomaton/markmaton@c0b21dac9ebd895c655e10036144b4cd8f73ec4c
- Branch / Tag: refs/tags/v0.1.8
- Owner: https://github.com/appautomaton
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: workflow.yml@c0b21dac9ebd895c655e10036144b4cd8f73ec4c
- Trigger Event: push

Release history Release notifications | RSS feed

This release

0.1.8 This release

Aug 3, 2026 5 files

0.1.7

Apr 14, 2026 5 files

0.1.5

Apr 9, 2026 5 files

0.1.4

Apr 9, 2026 5 files

markmaton 0.1.8

markmaton

Why it exists

Install

pip

uv tool

Quickstart

CLI

Python API

Output

Project shape

Documentation

Development

Release notes

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed

`pip`

`uv tool`