docling-project / docling-project/docling

[BEE] Docling Markdown Parser Doesn't Respect Heading Hierarchy

Open
#3,568 5 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
Python
Stars
66.4k
Forks
4.8k
Avg merge
2d 21h
Merged PRs (30d)
84

Description

### Bug
Markdown parser does not respect heading hierarchy. It creates a flat structure where all elements are siblings, while the HTML parser correctly nests content under their parent sections based on heading levels.

Both parsers should produce identical hierarchical structures since Markdown heading levels (`#`, `##`, `###`) define the same document hierarchy as HTML heading tags (`

`, `

`, `

`), but they don't.

### Steps to reproduce

Run `docling --from md --to json` and `docling --from html --to json` on `my_article.md` and `my_article.html` respectively. These documents are semantically identical analogues of each other. Then compare the results. You should receive copies of `my_article_md.json` and `my_article_html.json`, which I've attached here.

You will see that Docling's Markdown parser is **incorrectly flattening** the document structure. It should recognize that:

1. Content after `##` belongs to that section until the next heading of equal or higher level
2. `###` is a subsection of `##` (level 3 is child of level 2)
3. Content after `###` belongs to that subsection

The HTML parser correctly captures this hierarchy (sections contain their content), but the Markdown parser treats everything as siblings under `body`, ignoring the semantic meaning of heading levels.

### Docling version
2.84.0

### Python version
Python 3.12.13

[my_article.html](https://github.com/user-attachments/files/28739843/my_article.html)
[my_article.md](https://github.com/user-attachments/files/28739842/my_article.md)
[my_article_html.json](https://github.com/user-attachments/files/28739841/my_article_html.json)
[my_article_md.json](https://github.com/user-attachments/files/28739844/my_article_md.json)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.