html-table-rescuer

A robust Python tool to extract complex HTML tables and convert them into clean Markdown, JSON, or CSV formats.

Try it in your browser — an interactive Colab notebook, nothing to install.

Unlike simple formatters, this library features a Grid Logic Solver that correctly interprets rowspan and colspan attributes, normalizing complex HTML grids into perfectly aligned data structures.

How is this different from other table2md packages?

There is an existing package called table2md on PyPI.

• The existing package is a formatter. You feed it Python lists/dicts, and it draws a Markdown table.

• This package is an extractor and parser. It takes raw HTML source code, uses BeautifulSoup to parse the tags, mathematically resolves complex cell spans (rowspans/colspans), and builds an internal representation before exporting to Markdown.

The Problem:

Most parsers turn this <td rowspan="2"> into a misaligned mess:

| Header | Value |
|---|---|
| Spanned | Row 1 |
| Row 2 | |   <-- Everything shifts!

The Solution:

html-table-rescuer uses a grid solver to correctly normalize the matrix:

| Header | Value |
|---|---|
| Spanned | Row 1 |
| dito (Spanned) | Row 2 |

Architecture

Our pipeline ensures that complex HTML structures are safely converted without data loss or misalignment:

graph TD
    n1["HTML Input"] --> n2["BeautifulSoup Parser"]
    n2 --> n3["Grid Logic<br>(Rowspan/Colspan Solver)"]
    n3 --> n4["ParsedTable Data Object"]
    n4 --> n5["Markdown Export"]
    n4 --> n6["JSON/CSV Export"]
    n4 --> n7["LangChain/LlamaIndex/Haystack Wrappers"]

Installation

pip install html-table-rescuer

# With framework integrations
pip install "html-table-rescuer[langchain]"
pip install "html-table-rescuer[llamaindex]"
pip install "html-table-rescuer[haystack]"

Quick Start

from html_table_rescuer import TableParser

html_content = """
<table border="1">
  <tr>
    <th colspan="2">Header</th>
  </tr>
  <tr>
    <td>Data 1</td>
    <td>Data 2</td>
  </tr>
</table>
"""

# Initialize parser with your HTML
parser = TableParser(html_content)

# Parse all tables in the HTML
tables = parser.parse()

if tables:
    table = tables[0]
    
    # Export to Markdown (perfect for LLM context windows)
    print(table.to_markdown())
    
    # Export to JSON
    # print(table.to_json())
    
    # Export to CSV
    # print(table.to_csv())

Command Line

The package installs an html-table-rescuer command that reads from a file, a URL, or stdin:

# From a file
html-table-rescuer page.html

# From a URL
html-table-rescuer https://example.com/page.html

# From stdin (pipe or '-')
curl -s https://example.com/page.html | html-table-rescuer
cat page.html | html-table-rescuer - --format json

Options:

AI Framework Integrations

Every table becomes its own document, so retrieval never splits a table in half.

LangChain

from html_table_rescuer.integrations.langchain import HTMLTableRescuerLoader

docs = HTMLTableRescuerLoader("page.html").load()
print(docs[0].page_content)   # Markdown table
print(docs[0].metadata)       # {'source': 'page.html', 'table_index': 0, 'parser': 'html_table_rescuer'}

LlamaIndex

from html_table_rescuer.integrations.llamaindex import HTMLTableRescuerReader

docs = HTMLTableRescuerReader().load_data("page.html")

Works as a file_extractor in SimpleDirectoryReader, so entire folders are handled for you:

from llama_index.core import SimpleDirectoryReader

reader = SimpleDirectoryReader(
    "./docs",
    file_extractor={".html": HTMLTableRescuerReader()},
)
docs = reader.load_data()

Haystack

from html_table_rescuer.integrations.haystack import HTMLTableRescuerConverter

converter = HTMLTableRescuerConverter()
docs = converter.run(sources=["page.html"])["documents"]

Drops straight into a pipeline — unreadable sources are skipped with a warning rather than failing the run, and ParseConfig survives pipeline serialization:

from haystack import Pipeline

pipe = Pipeline()
pipe.add_component("converter", HTMLTableRescuerConverter())
result = pipe.run({"converter": {"sources": ["page.html"]}})

All three accept a ParseConfig to control rowspan handling and inline formatting:

from html_table_rescuer import ParseConfig, RowspanStrategy

config = ParseConfig(rowspan_strategy=RowspanStrategy.REPEAT_VALUE)
docs = HTMLTableRescuerReader(config=config).load_data("page.html")

Features

• HTML parsing via BeautifulSoup
• Recursive inline-tag formatting (keeps links, bold, and italic tags alive even if nested in divs)
• Complex rowspan and colspan grid resolution (using flexible strategies like filling cells with "dito" to preserve context for LLMs)
• Clean Markdown export
• Data Exports: JSON and CSV serialization from the ParsedTable object
• CLI: html-table-rescuer command with file/URL/stdin input and Markdown/JSON/CSV output
• AI Integrations: Ready-to-use LangChain Document Loader, LlamaIndex Reader (works with SimpleDirectoryReader), and Haystack Converter
• Robust against broken real-world HTML: invalid colspan/rowspan values, HTML comments, and oversized spans are handled gracefully

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Blog-Posts:

** Read the 1. blog:** How to Stop LLMs from Hallucinating on Complex HTML Tables ** Read the 2. blog:** How to Stop LLMs from Hallucinating on Complex HTML Tables