By ScoutMyTool Editorial Team · Last updated: 2026-05-28
Introduction
Every PDF-to-Markdown tool I have used converts prose cleanly and produces tables that render as a brick of pipe-separated text in the Markdown viewer. The fix is treating tables as a separate extraction problem: extract the cells, emit GFM with the correct alignment markers, escape literal pipes, handle newlines, and validate that pipe counts match before writing the file. Here is the working conversion pipeline that produces tables a Markdown parser actually renders — both the GitHub web view and the offline tools.
Vocabulary, quickly
| Term | Meaning |
|---|---|
| GFM table | GitHub-Flavored Markdown table syntax — pipes, dashes, alignment markers |
| Alignment marker | Colon in the separator row — left :--, right --:, center :-: |
| Cell padding | Spaces around cell content for human readability |
| Header row | First row, separator row beneath it |
| Pipe escape | \| in a cell when the content itself contains a pipe |
| Soft wrap | Line breaks inside a cell — most renderers do not support them in GFM |
| Spanning cells | GFM does not support colspan/rowspan; collapse or replicate |
Step by step
- Extract prose with a PDF-to-Markdown converter. pandoc, markdownify, or pdftotext piped through a structuring script.
- Extract tables separately. Camelot or pdfplumber to get per-cell content.
- Detect column type per column. Predominantly numeric vs text; choose alignment marker accordingly.
- Emit GFM rows with consistent pipe count. Header row, separator row of dashes with alignment, data rows.
- Escape literal pipes in cells. Run a regex replace pass: bare | inside cell content becomes \\|.
- Handle newlines. Replace with
<br>or collapse to a separator depending on parser support. - Interleave tables into prose in reading order. Use page-and-position metadata from extraction.
- Validate before save. Render the Markdown locally; if tables render correctly, save. If not, fix the extraction step.
Markdown table checklist
- Every table has a header row and a separator row with matching pipe count.
- Alignment markers reflect column content type (left for text, right for numbers).
- Literal pipes inside cells are escaped with backslash.
- Newlines inside cells are replaced with
<br>or collapsed; never left raw. - Spanning cells are handled deliberately (repeat, blank, or HTML markup).
- Rendered output checked in two parsers (GitHub web and one offline viewer) before publishing.
Common pitfalls in PDF-to-Markdown tables
- Inconsistent pipe counts across rows — even one off-by-one and the table falls back to paragraph rendering.
- Missing separator row — without the dashes row, the header is treated as data and the table never renders as a table.
- Trailing or leading whitespace inside cells that misaligns the visual source but renders fine — readable Markdown is also editable Markdown.
- HTML
<br>tags in cells in a parser that sanitizes HTML — the line break disappears, the cell collapses. - Spanning cells silently dropped — the table looks shorter than expected; decide explicitly whether to repeat values, leave blank, or escape into HTML markup.
- Tables reordered to the end of the document rather than placed in reading-order — fix the extractor, not the output.
- Numeric columns left-aligned because alignment markers default to left — right-align numbers; readers scan columns of figures down the right edge.
Related reading and tools
FAQ
- Why do my converted tables render as raw text in the Markdown viewer?
- Either the separator row is missing or the pipe count varies row-to-row. GFM requires a header row, a separator row of dashes below it (with the same pipe count), and consistent pipe count in data rows. A single off-by-one pipe and the parser falls back to treating the whole block as paragraphs. Validate pipe counts before saving.
- How do I preserve alignment from the PDF?
- Most PDF tables have visual alignment (left for text, right for numbers); detect the column type during extraction (predominantly numeric vs text) and emit the matching alignment marker — ":--" left, "--:" right, ":-:" center. Some converters set everything to default (left); override per column based on content type.
- My cells contain newlines and the table breaks. Fix?
- GFM tables don't natively allow newlines in cells. Two options: replace newlines with HTML <br> tags (which most GFM renderers honor), or collapse to a single line with a separator (en-dash, semicolon). HTML br is more faithful; the collapse is more portable across parsers that disable HTML.
- How do I handle cells with pipe characters?
- Escape with backslash: \|. The Markdown parser treats \| as a literal pipe inside the cell. Without the escape, the pipe is interpreted as a column boundary and the row count goes wrong. Run a post-pass that escapes every pipe inside cell content.
- Spanning cells (merged across columns or rows) — how?
- GFM does not support spanning. Options: (1) repeat the merged value in every cell it spans, (2) leave the spanned cells blank and rely on visual interpretation, (3) drop down to HTML <table> markup, which most GFM renderers honor. HTML markup is the highest-fidelity option but loses the editability of Markdown.
- Will my converter handle PDFs with both prose and tables?
- Most converters mix the two streams: convert prose to Markdown paragraphs, convert detected tables to GFM tables, interleave in reading order. Verify the reading order: tables sometimes get appended at the end of the document rather than placed where they appear in the PDF. Fix at the extraction step rather than reordering by hand.
Citations
- Wikipedia — “Markdown — flavors and extensions.” en.wikipedia.org/wiki/Markdown
- Wikipedia — “CommonMark — spec, extensions, and tables.” en.wikipedia.org/wiki/CommonMark
- Wikipedia — “Pandoc — format conversion engine.” en.wikipedia.org/wiki/Pandoc
Convert PDF tables to Markdown in your browser
Extract, emit GFM syntax with correct alignment and escapes, validate before save — ScoutMyTool runs the whole pipeline locally so source PDFs stay on your machine.
Open the PDF toolkit →