PDF to Markdown Converter

A PDF does not know what a heading is

This is the fact that explains everything else on this page, so it is worth stating first. A PDF describes a printed page. Inside it there are no headings, no lists, no paragraphs and no tables — only instructions of the form draw this glyph, in this font, at this size, at these coordinates. The structure you see is assembled in your eye out of position and size; nothing in the file says “this line is a section title”.

Everything this converter produces is therefore an inference — a good one on an ordinary document, a poor one on an unusual layout. A .docx, by contrast, carries real named styles, which is why converting the Word file gives a far better result than converting a PDF printed from it. If the source exists as a .docx, go and find it — the difference is not marginal.

What the converter actually does

The text comes out of the file in whatever order the generator wrote it, so the first job is geometry. Glyphs sharing a baseline are grouped into lines, and lines sorted down the page. The size covering the most characters is taken as the body size, and every line judged against it: a short line noticeably larger becomes a heading, and the distinct heading sizes are ranked so the biggest becomes #, the next ##, and so on. Short bold lines that sit in their own white space and do not end in sentence punctuation are promoted too — that is how a document using weight rather than size still gets structure.

Lists are found from their leading glyph — a bullet character, or a number followed by a full stop or bracket — which means the glyph has to be part of the page’s text for the list to be recognised at all. Nesting depth comes from left indentation measured against the margin the page actually uses, and a numbered list keeps the number it started at, so a list running from 5 comes back starting at 5. Bold and italic are recovered from the font each run is drawn in. Lines that stop without sentence punctuation, or run to the right edge of the column, are rejoined with the line beneath, because they are one wrapped paragraph rather than two sentences; hyphens split across a break are healed. Lines repeating at the top or bottom of most pages are treated as running heads and dropped, along with anything that is just a page number.

In the PDF                    As Markdown
──────────────────────────    ────────────────────────
Q3 Report      (18pt bold)    # Q3 Report
Revenue        (14pt bold)    ## Revenue
Revenue rose 12% year on      Revenue rose 12% year on year,
year, driven by renewals.     driven by renewals.
• Enterprise up 21%           - Enterprise up 21%
• Self-serve flat             - Self-serve flat
5. Renew the contract         5. Renew the contract
6. Re-price the plan          6. Re-price the plan
Q3 Report  ·  4      (7pt)    (dropped: running head)

Scanned PDFs have nothing to extract

The most common disappointment is a scan. A PDF from a scanner, photocopier or phone camera contains an image of each page and no text layer at all, so there is nothing for any extractor to read — this tool says so when it sees one, and it does not perform OCR. The fix is to recognise the text first: Acrobat’s Scan & OCR → Recognise Text, macOS Preview, or any dedicated OCR tool. Save the recognised copy and convert that. You can check any PDF in seconds: try to select a sentence — if it highlights, there is text to extract.

What does not survive

Bullets, sometimes — and this one surprises people, because the bullets are plainly there on the page. A bullet is only recoverable when the PDF stores it as a character in its text layer, which is what exports from Word, Pages, LibreOffice and LaTeX do. Several print-to-PDF paths do not: Chrome’s prints the disc as a small vector circle instead, so there is no bullet character anywhere in the file for any extractor to find, and pdftotext comes up just as empty. Those items still convert, with their text intact, but they arrive as an ordinary paragraph each rather than a - list. Putting the dashes back is a find-and-replace; better still, export the PDF from the word processor rather than printing it from a browser.

Lettered and roman lists lose their list-ness for a different reason: Markdown can only number, so a) b) c) and i. ii. iii. have no equivalent to convert into. Rather than silently renumbering them to 1, 2, 3 — which changes what the document says — those lines keep their labels verbatim as plain text. Numbered lists are fine, and keep the number they started at.

Tables are the big one. A PDF table is only text at positions, with the ruled lines drawn separately as graphics, so the rows come back as plain lines rather than a Markdown table. If the data started life in a spreadsheet, use Excel to Markdown or CSV to Markdown on the original instead.

Multi-column layouts interleave, because the reading order is down the page rather than down a column: a two-column paper alternates a line from each side. Export a single-column PDF if the source is yours. Images are dropped — Markdown can only link to a picture, and there is nowhere for these to live. Footnotes lose their tie to the reference and land wherever they sat on the page. Equations set as vector art vanish; equations set as text arrive scrambled. Fonts, colours and page layout go too, which is the point of Markdown rather than a failure of the conversion.

When it works well

Very well, for the ordinary case: single-column reports, papers, ebooks, manuals, contracts and documentation exported from a word processor. Those have one text column, a clear size hierarchy and real bullet characters, which is exactly what the heuristics look for. Expect the body text to be essentially perfect and the headings right most of the time.

Cleaning up the result

Budget a couple of minutes. Read down the headings and check the levels descend sensibly — an ### that should be a ## is the most common artefact. Then search for stray digits on their own line: page numbers the running-head detection missed. If paragraphs have been glued together where they should not be, turn off Rejoin wrapped lines and re-run. Anything that was a table needs rebuilding by hand. If the Markdown is headed for a Word document, Markdown to Word takes it the other way with real styles applied.

Where the Markdown goes next

Most people converting a PDF want a document out of a format built for printing and into one they can search, edit, diff or hand to a model. Bulguritto is a notes app built on the same idea: every note is stored as a plain .md file rather than a database row that exports Markdown on request, and those files sync across iPhone, iPad and Mac. Paste the output of this converter into a note and it stays a document any other program can read. It is free.