GuideBy MarkovoPublished October 27, 2026

HTML-to-Markdown GitHub Projects: Pick a Fit

Choose an HTML-to-Markdown GitHub project by its owner, runtime and conversion rules. Classify your input into three cases: a whole page whose navigation needs removing, a table whose header meaning must survive, or an export whose code needs a language label. Our local comparison found a table that kept every header word but lost the delimiter that makes it Markdown. That failure affected a Python library and the package that wraps it. ⁵⁶¹¹

Classify the HTML before choosing a repository

Whole pages, tables and code-bearing exports need separate rules for article boundaries, headers and language labels.

A page can meet several rows of this table. Our article sample contained page furniture, a labelled table and SQL code together. Removing the cookie banner would not repair a missing table delimiter, and retaining code text would not retain its language label. ¹¹

Identify HTML-to-Markdown GitHub projects by owner

The repository owner and dependency graph identify the conversion rules you are installing.

The unexecuted rows identify candidates for those runtimes. They do not inherit the results of the Python or Pandoc runs. A package's repository owner, its dependency lock and its enabled plugins belong in the integration record: “HTML-to-Markdown” alone cannot identify the code that produced an output.

Choose a header policy before enabling tables

A table converter needs a header policy and a working delimiter rule.

GFM represents a table with a header followed by a delimiter row. HTML can contain a table made entirely of data cells, so the converter must decide how to express the absent header. Markdownify leaves an empty header by default. Its inference option promotes the first data row instead. ⁷⁸

Output from our headerless data sample, unedited:

|  |  |
        | --- | --- |
        | Amber | Queued |
        | Birch | Done |
        

Output from our headerless data sample with inference enabled, unedited:

| Amber | Queued |
        | --- | --- |
        | Birch | Done |
        

The second output gives a task name and its state the role of column labels. Enable inference only when the first row contains labels that were encoded as ordinary data cells. If it contains a record, preserve the empty header or supply labels from the source schema. ⁷¹¹

An explicit HTML header can also fail because of its position. Our column-group sample put a colgroup element before a row of th cells, without a thead wrapper. Markdownify and MarkItDown retained the words but omitted the delimiter. ¹¹¹³

Output from our column-group header sample, unedited:

| Task | State |
        | Amber | Queued |
        | Birch | Done |
        

Markdownify's row converter requires the header row to have no preceding sibling element before it emits the delimiter. The column group violates that condition. Wrapping the same header row in thead restored the delimiter in our control. Turning on header inference did not restore it. ⁵¹¹¹⁴

The Turndown plugin's historical empty-header report illustrates the last distinction. Its example contained an empty header cell, rather than our column group or all-data table. We did not run that JavaScript implementation, so the report cannot establish its output here. ¹⁰

Configure the Python path you already use

Markdownify exposes the rules directly, while MarkItDown inherits its HTML table behavior.

For a known article template, select the article before converting it and extract the language from the code element. This example stops if the expected region is absent. A fallback to the entire page would put navigation back into the document. ⁷

from pathlib import Path
        from bs4 import BeautifulSoup
        from markdownify import markdownify
        
        def code_language(pre):
            code = pre.find('code')
            for value in (code or pre).get('class', []):
                if value.startswith('language-'):
                    return value.removeprefix('language-')
            return ''
        
        soup = BeautifulSoup(Path('input.html').read_text(), 'html.parser')
        article = soup.select_one('main article')
        if article is None:
            raise ValueError('No main article element in this input')
        Path('output.md').write_text(markdownify(
            str(article), heading_style='ATX', code_language_callback=code_language))
        

Output from our article sample with region selection and the callback, unedited:

```sql
        SELECT pid, wait_event_type, query
        FROM pg_stat_activity
        WHERE state = 'active';
        ```
        

The callback restored the SQL label that the unconfigured conversion omitted. It relies on a language class in the source and does not infer a language from the code itself. The selector removed the page furniture on this template. Neither setting repaired the column-group table, because both operate outside the table-row rule. ¹¹¹²

MarkItDown is useful when HTML belongs to a workflow with other document formats and you want a shared entry point. Its HTML path removes script and style elements, then converts the body through its Markdownify subclass. On our full-page input, that boundary included the cookie banner and navigation. ⁶¹⁶

from pathlib import Path
        from markitdown import MarkItDown
        
        result = MarkItDown(enable_plugins=False).convert('input.html')
        Path('output.md').write_text(result.text_content)
        

Output from our full-page sample through MarkItDown, unedited:

We use cookies to improve your experience.
        
        Engineering notes from the infrastructure team
        

That wrapper also reproduced the column-group delimiter failure. Apply a source-structure correction or choose an independently tested writer when that rule blocks your input. ¹¹

Markovo's archived HTML run offers a hosted comparison for the article boundary: it excluded the banner and navigation while keeping the article, but its code fence lost the SQL language label. The successful job therefore did not establish complete code preservation. The archive predates this local comparison and covers only the article baseline. For a hosted public URL to Markdown route, the product supports publicly accessible HTTPS pages in Signed-in Beta. This uploaded-HTML result does not establish URL-fetching behavior, access to protected pages or GitHub rendering. The added header probes were not run through the service. ¹¹¹⁵

Output from our archived hosted article sample, unedited:

# Debugging Slow Database Migrations
        
        A migration that runs in seconds on a laptop can hold locks for minutes in production. The difference usually comes from table size and from other sessions waiting behind the migration.
        

Use Pandoc when you want a GFM writer

Pandoc retained the delimiter that our Python outputs dropped on the column-group input.

Use an explicit input reader and output writer so the command records the format decision. This command converts a local file and performs no browser rendering. ⁹

pandoc -f html -t gfm --wrap=none input.html -o output.md
        

Output from our column-group header sample through Pandoc, unedited:

| Task  | State  |
        |-------|--------|
        | Amber | Queued |
        | Birch | Done   |
        

Pandoc kept the delimiter for the column-group input without the header wrapper. On the full-page sample it also kept the SQL language label and excluded the page furniture. Those observations describe the supplied HTML. They do not establish an article extractor for arbitrary page layouts. Pandoc parses into an intermediate document representation before writing Markdown, and that representation can lose details from richer input. ⁹¹¹

For a Python pipeline with a known DOM template, Markdownify lets you state the article boundary and language handling in code. MarkItDown keeps that HTML table dependency while offering a common document entry point. Pandoc supplied a separate GFM-writing path for the structural case that failed in our Python outputs. For Go or JavaScript integration, use the owner and plugin map to identify a candidate, then apply the same header, region and language requirements to that implementation. ¹³¹¹

How we tested

The comparison covers local HTML conversion, with a separately dated Markovo baseline.

The local runs took place on 2026-10-27 using Python 3.11.14, MarkItDown 0.1.8, Markdownify 1.2.3, Beautiful Soup 4.15.0 and Pandoc 3.11. All Markdownify profiles explicitly used ATX headings. The selected profile added article selection and a code-language callback. The inference profile enabled table_infer_header=True. These profiles are controls of one library, and MarkItDown also uses that library for HTML. They are not independent engines. ⁶⁷¹²

Markovo is the service we build. It ran through the same corpus and scorer as the other paths; its row is reported in full, including where it scored lower.

The shared Markovo corpus here is only article.html. Its API snapshot records a succeeded job on 2026-10-14 with pages_total=1 and pages_ocr=0. We reused the downloaded Markdown without another API call. The snapshot does not identify the conversion-engine version, and its rate-card identifier is not such a version. The added header probes were not executed on Markovo. Its output loses the SQL language label, a property not measured by the code-text score. No timing or service-wide quality comparison follows from this archive. ¹⁵

Each input has a same-stem .truth.json. The upstream full-page input was reused unchanged. The runner creates the other inputs and byte-identical .txt mirrors. The mirrors are evidence files, not rendered HTML. No PDF, scan, Office, GitHub.com or VS Code test is represented by this HTML subset. ¹²

From this repository root, with the existing offline environment:

PYTHONDONTWRITEBYTECODE=1 tools/lab-venv/bin/python runs/2026-10-27-markovo-html-to-markdown-github/lab/run_html.py
        PYTHONDONTWRITEBYTECODE=1 tools/lab-venv/bin/python tools/lab_score.py --lab runs/2026-10-27-markovo-html-to-markdown-github/lab --out runs/2026-10-27-markovo-html-to-markdown-github/lab/scores.json
        

The runner records all options and commands in the execution manifest. It runs MarkItDown and all Markdownify profiles on every selected input, and calls Pandoc with -f html -t gfm --wrap=none. The strict standalone examples were also executed with the article input: Markdownify example and MarkItDown example. Turndown, the Go implementation and the Rust implementation were not executed for this guide. ¹⁰¹²

The table below copies the selected cells from scores.json. P is prose_recall, the fraction of truth sentences of at least four words found after normalization. O is reading_order, adjacent paragraph anchors occurring in order. H is heading_level_exact, expected ATX headings at the expected level. R is table_rows_intact, each row's cell strings found together on an output line. T is table_header_intact, header strings found on one line. Pipe is table_pipe_detected, a pipe row followed by a delimiter. C is code_block_intact, expected code lines found within fences. B is boilerplate_excluded, absent navigation/banner/footer truth strings. Fractions are not a composite quality score. ¹¹

N/A means an absent measurement, except headerless T: the scorer emits zero for the absent truth header, which we mark N/A rather than call a missing header. Markovo NT means not tested on that input. The archived elapsed value is a placeholder, not a measured duration. Local seconds are single executions, not a throughput benchmark.

These checks do not measure semantic column alignment, language labels, merged-cell meaning, link reachability or rendered appearance. The inference profile still receives full row-text credit after promoting data into a header. Likewise, the column-group failure retains header-text credit while failing Pipe. Raw output inspection and the installed function snapshot explain those differences. ⁵¹¹¹⁴

Raw outputs use lab/<profile>/<input-stem>.md, including lab/markdownify/colgroup-header.md, lab/markdownify/colgroup-thead.md, lab/markdownify-infer-header/headerless.md, lab/markdownify-selected/article.md, lab/markitdown/article.md, lab/pandoc-gfm/colgroup-header.md and lab/markovo/article.md. Corpus notes distinguish upstream files, local controls and unmeasured properties. ¹²

Sources

1. Go html-to-markdown README
2. Rust-core html-to-markdown README
3. Turndown GFM table rules
4. Turndown README
5. Markdownify table and code conversion source
6. MarkItDown HTML converter source
7. Markdownify options
8. GitHub Flavored Markdown specification
9. Pandoc User's Guide
10. Historical empty-header conversion report
11. Full scorer output
12. Offline HTML conversion runner
13. Publishable colgroup input mirror
14. Installed converter function snapshot and hash
15. Archived Markovo API response
16. MarkItDown Markdownify subclass