Why does a PDF lose its headings and lists when converted to Markdown?
A PDF stores where text sits, not which line is a heading, so a converter has to guess. On 2026-10-11 our test found one of three section headings and no real bullet list. After a fix, the same file on 2026-10-13 gave all three headings and a list. The fix covers numbered headings only.
What did we convert?
We made two samples with invented content. The first is a two-page report with a title, three numbered section headings, a bullet list, a table, a figure with a caption, and a running page header and footer. The second is a one-page paper in two columns, with 24 numbered sentences so that the reading order would show. We converted both with PDF to Markdown on osmanthdocs.com and read the Markdown it produced. Both results were labelled "Looks good" with no notes. The table below is the first run, dated 2026-10-11, before the change.
| In the PDF | In the Markdown, 2026-10-11 |
|---|---|
| Title | Kept as a level-1 heading (#) |
| Section "2. Regional results" | Kept as a level-2 heading (##) |
| Sections "1. Summary" and "3. Notes" | Not headings. "1. Summary" is a plain line, and "3. Notes" was joined to the start of the paragraph below it |
| Three bullet items | Three separate lines starting with a dot, not Markdown list items |
| Table (4 columns, 4 data rows) | A Markdown table, every value as in the PDF |
| Figure and caption | The image linked from the Markdown, with the caption as a line below |
| Page header and "Page 1" footer | Left out |
| Two columns with 24 numbered sentences | All 24 in reading order, down the left column then the right, and both column headings kept as level-2 headings |
So the label "Looks good" does not mean every heading was found. It means the tool saw no warning signs. We did not find out why the layout model missed two of the three section headings.
What changed on 2026-10-13?
The PDF itself records each character's font size and weight, which the layout model does not use for this. After the model has run, the tool now looks at a line that starts with a section number such as "1." or "2.1", is larger or bolder than the body text, sits on its own line and does not read like a sentence. Such a line becomes a heading. Lines that start with a bullet mark such as "·" or "•" become Markdown list items. We re-ran the same two-page file on the live site: "1. Summary", "2. Regional results" and "3. Notes" are all level-2 headings, the three bullets are list items, and "3. Notes" is no longer joined to the paragraph below it. The table, figure and caption are unchanged.
We also ran the change over 125 real PDFs from our test set. It altered none of them, because their numbered lines were either body text or already headings, so it has not been shown to help on real documents yet. It does not look for headings without a number, such as a bold line with no section number. When we tried that on the same 125 PDFs, it mostly picked up author lines and small print on cover pages, so we left it out.
What can Markdown express?
Markdown can only keep what you can write in it. In the CommonMark specification, a heading is one to six # characters followed by a space, and a bullet item starts with -, + or *. An ordered item is up to nine digits followed by . or ). Tables are not part of core CommonMark. They are an extension in GitHub Flavored Markdown: a header row, a delimiter row and data rows, with inline content in the cells and no block-level elements inside them. The part of the GFM specification we read says nothing about merged cells.
The converter's engine, Docling, says it analyses page layout, reading order and table structure, and exports Markdown. That is a model's reading of the page, which is why a heading can be missed even when it looks obvious to you.
What should I check after converting?
- Search the Markdown for each section name you expect and confirm it starts with
#. Headings without a section number are the most likely to be missed. - Look for lines that begin with a dot, a bullet character or a number and a period. They may be list items that were not converted.
- Compare every table against the PDF, and compare totals.
- Open the links to extracted images to confirm each is there.
- If you plan to split the Markdown by heading, check the headings first, because sections follow the headings that were found.
What are the limits?
In our own tests with generated sample pages, some clean tables were not detected as tables at all, and the result did not always say so. Compare every table with the original page, and treat a missing table or any warning as a reason to look closer.
Your PDF is uploaded to our servers, where open-source software processes it. It is not sent to any third-party AI or document API. The uploaded PDF is deleted as soon as processing finishes, and the results stay for 60 minutes. Files can be up to 50 MB and 100 pages. The privacy page has the full wording.
Next: how to give a PDF to ChatGPT or Claude, which uses the same converted text.