Heading from pdf

[roninio]

I have a PDF document containing headings of various sizes and styles. After converting the PDF to a Markdown file using DocLing, I've noticed that all headings are uniformly converted to level-2 headings (##), regardless of their original size or importance in the PDF.

I would like to know how to properly configure DocLing, or if there's an alternative method, to accurately represent the original heading hierarchy from the PDF in the resulting Markdown file. Specifically, I need the Markdown headings to reflect the relative size and importance of the headings in the original PDF (e.g., larger headings should become #, smaller headings ###, etc.).

Could you please provide information on how to achieve this? Thank you."

[kaumnen]

PyMuPDF has a get_toc [0] method that returns a table of contents

a quick example of returned ToC with simple=True (more info in the linked docs):

[
    [1, "Heading 1", 22],
    [2, "Heading 2", 33],
    [3, "Heading 3", 44],
    [4, "Another heading 4", 55]
]

elements format:
[<heading level>, <heading text>, <page its on>]

what you can do is:

1. convert the pdf and .export_to_markdown() [1]
2. open the same pdf file with PyMuPDF, extract ToC
3. go through the markdown, check and update (add or remove) # where needed based on the <heading level> from the ToC

---

[0]: https://pymupdf.readthedocs.io/en/latest/document.html#Document.get_toc

[1]: https://docling-project.github.io/docling/reference/docling_document/#docling_core.types.doc.DoclingDocument.export_to_markdown

[PeterStaar-IBM]

@roninio Note that the docling-parse can also provide the TOC and populate it (see here: https://github.com/docling-project/docling-core/blob/763e1364ff0b95388696ccd3d69f150718012a3a/docling_core/types/doc/page.py#L463).

We plan to propagate this info and use it to improve the heading tree.

[JohannKaspar]

Looking forward to this feature!

[mrtj]

Both @kaumnen’s approach using PyMuPDF and @PeterStaar-IBM’s suggestion in docling-parse extract only the TOC from a PDF if the file already contains a TOC saved as a “hierarchical outline tree” (an optional PDF feature). If the PDF was digitally born and the PDF creator supported outlines and saved them to the file, you’re good to go. Typically this isn’t the case for scanned pages or even digitally born PDFs created without an outline. Docling does recognize headers by other means, but it classifies all headers as second level. Is extending the header detector to support multiple levels on your roadmap?

[krrome]

Hi @mrtj and @roninio I have been working on this topic. I'm hoping to open a docling-PR on this topic, but due to the complexity of integrating the solution I decided to make a little package docling-hierarchical-pdf, that is tailored exactly to work with Docling and adds inference of PDF hierarhies - it works with scanned PDFs as well as text-based PDFs. At the moment:

• it is still in an early stage, but please do give it a try and give feedback. I ran a bunch of tests and was happy with the performance. The limitation, if any, seems to be more on the docling document parsing side.
• I am inferring document hierarchy based on header numbering and header styles. Next I will add PDF-bookmark-support along the lines of my approach in this issue: Identify table of contents for better chunking Hierarchy Identification #287 (comment)

If there is interest by the maintainers in integrating my solution into docling, I am happy to work on that too.

[PeterStaar-IBM]

Yes, @krrome , we should definitely need to look into this!

[krrome]

Update: v0.1.0 of docling-hierarchical-pdf now also attempts to use the TOC (aka bookmarks) from the PDF metadata, if there is one. Otherwise it falls back to using style-based inference. Please give it a try and report issues if there is any problem.

[Sirnii]

Yes, @krrome , we should definitely need to look into this!

Hi!
Any is it somewhere close on your list? :)

Thanks for great job,
K

[filip-komarzyniec]

Hi!

Is anyone actively working on incorporating docling-hierarchical-pdf into docling? Is it somewhere on the product's roadmap at all?

This seems like quite an important feature for improving the quality of information retrieval from pdf files serialized to markdown.

[PeterStaar-IBM]

@filip-komarzyniec It is currently being done at the docling-agent level.

[zelinyang-create]

I also encountered this problem when preparing PDFs for RAG, where the converter could detect headings but flattened most of them into the same Markdown level.

I built a small experimental project that tries to address this with a VLM-based PDF-to-Markdown pipeline:

https://github.com/zelinyang-create/DocVisionMD

Instead of relying only on embedded PDF outlines/bookmarks, it renders pages as images, asks a VLM to infer page-level structure and heading levels, then converts pages to Markdown with post-processing for heading normalization, TOC cleanup, table-title handling, and table repair.

It is still early and not meant to replace Docling, but it may help in cases where the PDF has no reliable outline tree or where visual layout is needed to infer hierarchy.

[PeterStaar-IBM]

@zelinyang-create Docling does the VLM's natively already if you use the VlmPipeline. To do the TOC/outline, I would encourage everyone to start using the docling-agent (eg with this config: https://github.com/docling-project/docling-agent/blob/main/task-configs/editor.yaml)