By ScoutMyTool Editorial Team · Last updated: 2026-05-27
Introduction
I converted a 300-page technical PDF to Markdown the lazy way once and spent an entire afternoon fixing broken code fences and tables that came out as one long line. The PDF format does not have a concept of "code block" or "table" — it has glyphs and positions, and the converter has to infer structure. Once I understood that, the conversion got dramatically cleaner with a two-pass approach: structure first, prose second. This is how I do it now and what to watch for to know when a converter is silently dropping rows.
Vocabulary, quickly
| Term | Meaning |
|---|---|
| Text layer | The selectable text inside the PDF — required for any clean conversion |
| Glyph stream | How PDFs store text: x/y positions of individual glyphs |
| Code fence | Markdown ``` block — needs accurate line preservation |
| Monospace heuristic | Converter detects code by detecting monospace font runs |
| Table cell | A bounded region of text — converters infer from x/y position gaps |
| Inline code | Single-backticked code in prose — easily lost in PDF conversion |
| Ligature | Joined glyphs (fi, fl) that some converters mishandle into garbage |
Step by step
- Confirm the PDF has a real text layer. Try to select text on a code snippet. If selection works and copies cleanly, you have a text layer. If not, OCR first.
- Run a structure-aware converter, not a regex one. A converter that uses font metadata (Courier/monospace) and column positions produces much cleaner output than one that just streams glyphs.
- Inspect code blocks first. Open the Markdown, scroll the first 5 code blocks, confirm indentation and line breaks are intact. Code is the part that breaks most visibly.
- Inspect tables next. Render the Markdown and confirm tables have rows separated correctly. Misaligned columns mean the converter mis-inferred column boundaries.
- Fix ligatures in a second pass. Search-and-replace `fi`, `fl`, `ff` ligatures back to their components if the converter passed them through as the joined glyph.
- Restore inline code with a heuristic. Any run of monospace within a paragraph should be wrapped in backticks. Some converters mark this; others lose it — a regex pass on Courier-detected spans recovers most.
- Validate headings. Markdown headings should match the PDF's heading hierarchy. If H2 and H3 got flattened to bold, the structure is lost — pick a different converter.
- Spot-check against the source. Open the PDF and the Markdown side by side, scroll to three random pages, confirm content matches. Catches dropped paragraphs and out-of-order blocks.
Practical checklist before you send
- Always do a fast eyeball pass over the first 5 code blocks and the first 3 tables — those are the structures most likely to be silently mis-rendered, and a 30-second scan saves an hour of mid-document discovery.
- Run the conversion on a single chapter first to calibrate the converter's heuristics; if code fences and tables come out clean on one chapter, they will across the whole book.
- Preserve heading hierarchy by checking that your H2/H3 distinction in the PDF survives as `##` vs `###` in Markdown; a converter that flattens both to bold loses your structure.
- Strip ligatures in a second pass — search Markdown for U+FB01 through U+FB06 and replace with their components.
- When a converter drops a paragraph entirely, the usual cause is unusual column layout (sidebars, callout boxes); extract those regions separately rather than fight the auto-detect.
- Keep the source PDF alongside the Markdown — Markdown is the working format, the PDF is the canonical record-of-truth for re-extraction when needed.
Related reading and tools
FAQ
- Why are my code blocks coming out as flat paragraphs?
- The converter is not detecting the monospace font signal. Most PDFs render code in Courier, Menlo, or another monospace family, and a font-aware converter wraps those runs in code fences. A glyph-stream converter that ignores font metadata produces flat paragraphs. Switch to a converter that exposes font handling, or post-process: detect long runs of monospace glyphs in the underlying PDF and wrap with ``` in the output.
- My tables come out as one long line — what is wrong?
- The converter did not infer column boundaries. Tables in PDFs are typically positional (text at x=100, x=200, x=300 in the same line) rather than tabular markup. A converter has to detect the column structure from the x-positions; if it cannot, it serializes the row as one line. Use a converter with explicit table detection or convert the table separately by region selection.
- Should I OCR the PDF before converting?
- Only if it is image-only. If the PDF has a real text layer (test by selecting text), OCR would re-derive the text from the rendered glyphs and lose all font metadata — which kills code-block detection. Skip OCR for born-digital PDFs. OCR only scanned ones, accepting that code-block and table fidelity will be poorer.
- How do I handle ligatures and weird character substitutions?
- Two passes: first, convert and look at the output. If you see U+FB01 (fi) or similar Unicode ligature characters, run a regex to split them back to fi, fl, ff. Some converters do this automatically; others do not. The character set to watch for is U+FB00 through U+FB06 — the standard Latin ligatures.
- Can I preserve PDF footnotes as Markdown footnotes?
- Some converters do this with the `[^1]` syntax — most do not. The trick is that footnotes in PDFs are at the bottom of the page with a superscript reference number elsewhere; the converter has to associate them. If the converter does not, the cleanest fallback is to keep footnotes as parenthetical inline citations rather than chase the Markdown footnote syntax.
- Is there a difference between converting one page vs the whole PDF?
- Whole-PDF conversion lets the converter use structure across pages (continuing a table from page 2 to page 3, a heading on page 5 anchoring a TOC). Page-by-page conversion is faster but loses cross-page structure. For a technical book, do the whole PDF and accept the longer runtime. For a quick extract of one chapter, page-range is fine.
Citations
- Wikipedia — “Markdown — syntax for code blocks, tables, headings.” en.wikipedia.org/wiki/Markdown
- Wikipedia — “PDF — text and glyph stream structure.” en.wikipedia.org/wiki/PDF
- W3C — “Tagged PDF structural elements (informative).” www.w3.org/TR/WCAG20-TECHS/pdf.html
Convert PDFs to clean Markdown, locally
Run the conversion in your browser; tune the structure detection without uploading the PDF anywhere.
Open the PDF conversion tools →