Claupt practical guide
How to Convert a PDF to Markdown for RAG
Turn a PDF into reviewable Markdown while preserving the headings, lists, tables, and reading order a RAG pipeline needs.
Why Markdown helps RAG ingestion
Markdown gives extracted text a lightweight structure. Headings can mark section boundaries, lists retain grouping, and tables can remain readable without carrying the layout code of the original page. That structure makes it easier to create meaningful chunks and attach section paths as metadata.
Conversion does not automatically make a document accurate or retrieval-ready. The Markdown is an intermediate representation that should be checked against the source.
Identify the kind of PDF first
A digitally generated PDF usually contains selectable text and is the simplest case. A scanned document contains page images and needs optical character recognition. Mixed PDFs may combine selectable text, scans, forms, figures, and tables. Password protection or unusual fonts can also change what a parser can recover.
Test a few representative pages before processing a large collection. Include a dense table, a multi-column page, a page boundary, and any section with footnotes or figures.
Preserve reading order and hierarchy
Check that multi-column pages are read in the intended order and that headings remain attached to the paragraphs they introduce. Keep numbered steps, bullet nesting, captions, and table headers when they affect meaning. Remove repeated page furniture such as running headers and page numbers only when it does not carry useful context.
For tables, compare important values and row-to-column relationships with the original. A plausible-looking Markdown table can still contain shifted cells.
Create chunks after reviewing the Markdown
Split by document structure where possible. A section heading and its content usually form a better unit than an arbitrary number of characters. If a section is too large, split at paragraphs or sentences and retain the section path with every child chunk. Avoid separating a table from its title, units, or explanatory note.
Store source-page references or another stable locator alongside each chunk so a user can verify an answer against the original document.
Build a repeatable quality check
Keep the original file and converted Markdown together. Compare character counts, headings, table counts, and a sample of important numbers. Flag empty pages, very short extractions, repeated text, or unexpected character substitutions. For high-stakes documents, require human review or a second extraction method.
Once the extraction is trustworthy, test retrieval with questions whose answers appear in different sections, tables, and page layouts. This separates ingestion problems from embedding or retrieval problems.
Worked example: a table that loses its units
Suppose the source table is headed “Quarterly revenue (USD thousands)” and contains a row for North: Q1 = 120, Q2 = 145. Extracting only “North 120 145” loses both the period labels and the scale.
## Quarterly revenue (USD thousands)
| Region | Q1 | Q2 |
| --- | --- | --- |
| North | 120 | 145 |
Source: quarterly-report.pdf, page 4
Note: figures exclude tax.In this fictional example, the answer to “What was North's Q2 revenue?” is USD 145,000, not USD 145. Keep the heading, units, and note together when creating a chunk. Check the source page before applying any conversion to the numbers.
Before you index the converted text
- Ask a question about one table cell and verify the row, column, and unit.
- Check one paragraph that crosses a page boundary for missing or duplicated words.
- Confirm that any footnote qualifying the answer is still attached.
- Keep a source locator with each chunk so an answer can be checked.
Claupt's PDF to Markdown tool is a starting point for supported text documents. Scanned pages need an OCR workflow; complex tables and layouts may require manual repair. After review, use the Smart Text Chunker and inspect the resulting boundaries.
Convert a supported document locally, then inspect the Markdown before adding it to a RAG pipeline.