When a PDF becomes Markdown, the most valuable thing it carries across is its headings. Headings are what let you navigate a long document, build a table of contents, and find a section again later. But a PDF does not store headings as headings. It stores characters at positions on a page, in particular fonts and sizes. A converter that turns a PDF into Markdown must therefore infer which text is a heading, and the main clue it uses is size: text set larger than the body text is probably a heading.
PDF to Markdown works this way. It extracts the PDF's text layer, treats noticeably larger type as headings — with larger sizes becoming higher-level headings — detects lists from markers, and separates paragraphs from layout gaps, all in your browser. Understanding that inference, and its limits, helps you predict where a conversion will go right and where it will need a hand.
Size as a signal
In a well-typeset document, the size hierarchy is consistent. The title is the largest text, section headings are smaller but still clearly larger than body text, and subsections sit between the two. A converter can learn that hierarchy from the document itself: it looks at the sizes present, finds the body size that most text uses, and treats larger sizes as headings in proportion to how much larger they are.
That works because authors use size meaningfully, most of the time. A chapter title is meant to stand out, and making it larger is the standard way to do it. The converter is simply reading the same visual signal a human reader reads, and translating it into Markdown markers — one hash for a top-level heading, two for a section, three for a subsection, and so on.
Lists work on a similar principle, but with markers rather than size. A line beginning with a bullet, dash, or number is treated as a list item. Paragraphs are separated by gaps: where the vertical space between lines is larger than the space within a paragraph, a new paragraph begins. Each of these is a reasonable inference from how documents are normally laid out.
What fools the detection
The trouble starts when size is used for something other than hierarchy. A pull quote set in large type, a caption in a display font, a drop cap, or a decorative heading that is large but not structural can all be misread as headings. The converter cannot know that a large line is a quote rather than a section title; it only sees that the line is large.
Inconsistent styling fools it in the opposite direction. If a document's headings vary in size — because it was assembled from several sources, or because a heading was typed in body size by mistake — the converter may miss a real heading or assign it the wrong level. A section heading set at the same size as body text, distinguished only by bold weight or colour, is invisible to a size-only detector.
Layout adds further traps. Multi-column pages can interleave columns, so a heading from the second column lands in the middle of the first column's text. Tables can produce lines that look like headings because their cells use larger or bolder type. Sidebars and footnotes, set in boxes or at the foot of a page, can be read in the wrong order entirely. None of these are converter bugs in the usual sense; they are the predictable result of inferring structure from appearance, where appearance is ambiguous.
Worked example: a fictional community handbook
Consider a fictional community handbook, invented for this example, written by a fictional editor named Sam, at sam@example.org. The handbook has a title, four sections, and a pull quote on the opening page: a large, inspiring sentence from a local resident, set in type larger than the section headings. It also has a sidebar on one page listing opening times, set in a shaded box.
Converted to Markdown, the title and section headings mostly come out correctly, because their sizes follow a consistent hierarchy. But the pull quote also becomes a top-level heading, because it is the largest text on its page after the title. A reader navigating by headings would find a "section" that is really a quotation, and a table of contents built from the headings would include it as if it were a chapter. The sidebar's opening times, meanwhile, land as ordinary lines after a paragraph, losing the sense that they belong together.
Sam fixes both by hand, which is the expected workflow. He demotes the pull quote to an ordinary paragraph, perhaps with quotation marks, and groups the opening times under a small heading of his own. Those two edits take a minute, and the rest of the conversion — dozens of headings and lists — is correct. The lesson is not that detection failed, but that a quick check of the heading outline catches exactly the cases where size misleads.
If Sam needs to rearrange the handbook's pages before converting, Organize PDF can do that, and if he wants to check his own writing for readability afterwards, Content Analyzer scores it.
Honest limitations
Tables, multi-column layouts, and complex formatting do not convert perfectly, and heading detection is part of that story. A converter that reads size cannot recover structure that was never encoded in size — a heading distinguished only by colour, a list implied only by indentation, a table whose structure lives in grid lines rather than text. Those cases need human judgement, and no size-based detector will fix them on its own.
Scanned PDFs add a further limit. Without a text layer, there are no font sizes to read at all, so heading detection cannot even begin until OCR has added text. And even on a clean, well-typeset document, the output should be checked against the original. Skim the heading outline, compare it with the document's contents page if it has one, and fix the handful of headings that size alone got wrong. That check is short, and it is what turns a good conversion into a reliable one.
For improving the readability of text once it is in editable form, see how to improve readability.
FAQs
How does PDF to Markdown decide what is a heading?
Mainly from font size. Text set noticeably larger than the body text is treated as a heading, with larger sizes becoming higher-level headings. It is an inference from typography, not a label stored in the PDF.
Why did a quote become a heading in my conversion?
Because it was set in large type. A pull quote, a caption in a display font, or any large decorative line looks like a heading to a size-based detector. Demote it to ordinary text by hand when you tidy the output.
Why was a real heading missed?
Usually because it was not larger than the body text — it may have been distinguished only by bold weight, colour, or spacing. Size-only detection cannot see those signals, so the heading needs to be marked by hand.
Should I trust converted headings without checking?
No. Skim the heading outline against the original document, especially on pages with quotes, sidebars, tables, or multi-column layouts. The check is quick, and it catches the cases where appearance misleads the converter.
human review pending client designation