Why use Markdown for LLMs?
PDFs are designed to look good on a page, not to be easy for software to read.
A PDF can contain headings, paragraphs, lists, tables and multiple columns, but much of that structure isn’t obvious when you extract the text. A simple text extraction can leave you with a long block of content where it’s difficult to tell which text belongs to which section.
Markdown gives that content some structure again.
A document like:
# Quarterly Report
## Summary
Revenue grew 18% quarter over quarter, driven by new self-serve signups.
## Details
- New customers: 1,240
- Churn: 2.1%
- Net revenue retention: 112%
is considerably easier to work with than a plain-text dump of the same document.
That’s particularly useful when you’re feeding documents into an LLM or building a RAG system. Headings give you useful boundaries for chunking, while lists and other formatting remain intact.
Feeding a vector store? Markdown is a useful format to start with.
How PDF to Markdown conversion works
The converter extracts the text from your PDF and uses the document’s layout to reconstruct its structure.
It looks at things such as:
- Font sizes and styles
- Heading hierarchy
- Paragraph spacing
- Lists
- Reading order
- Text positioning
It then turns that structure into Markdown.
For example, a large heading in the original PDF can become a # heading, with smaller section headings becoming ## or ###. Lists are converted to Markdown lists and paragraphs are kept separate.
For text-based PDFs, this happens directly in your browser. Your file doesn’t need to be uploaded to a server just to extract its text.
Chunking Markdown for RAG
If you’re converting PDFs for a RAG pipeline, the Markdown is only the first step. How you split it can have a big effect on what your retrieval system gets back.
A simple approach is to use the document’s headings as your first set of chunk boundaries.
For example:
# Product Documentation
## Installation
## Configuration
## Authentication
## API Reference
Instead of splitting every 1,000 characters, you can start with sections such as ## Authentication or ## Configuration.
That means a chunk is more likely to contain a complete section rather than half of one section and half of another.
For longer sections, split them again at paragraph boundaries. When you do that, keep the relevant heading with each chunk.
For example:
Product Documentation > Authentication
Authentication works using API keys...
You can also store the heading hierarchy as metadata alongside the embedding:
{
"heading_path": ["Product Documentation", "Authentication"]
}
That gives you useful context when displaying search results or generating citations.
A practical workflow is:
- Convert the PDF to Markdown.
- Split the document at headings.
- Split unusually long sections at paragraph boundaries.
- Keep the heading or heading path with each resulting chunk.
- Store the heading path as metadata in your vector database.
The right chunk size depends on your model and your documents, so there’s no single number that works for every RAG system.
PDF to Markdown in code
The browser converter is useful when you have a PDF or two to process manually. If you’re building a document pipeline, you can use the API instead.
Send the PDF to the extraction endpoint and request Markdown as the output format.
curl -X POST https://api.pdftojson.dev/v1/extract \
-H "Authorization: Bearer $KEY" \
-F file=@document.pdf -F format=markdown
import requests
response = requests.post(
"https://api.pdftojson.dev/v1/extract",
headers={"Authorization": f"Bearer {KEY}"},
files={"file": open("document.pdf", "rb")},
data={"format": "markdown"},
)
md = response.json()["content"]
const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));
form.append("format", "markdown");
const { content } = await fetch("https://api.pdftojson.dev/v1/extract", {
method: "POST",
headers: { Authorization: `Bearer ${KEY}` },
body: form,
}).then((r) => r.json());
The API is useful when you need to process PDFs automatically, handle larger volumes, or add OCR to your pipeline.
What about difficult PDFs?
Not every PDF is straightforward. A document can look perfectly normal to a person while being surprisingly awkward to parse.
Here are some of the common cases.
Scanned PDFs
A scanned PDF is usually a collection of images rather than actual text. There’s nothing for a normal text extractor to copy, so OCR is required.
The browser converter is intended for PDFs with a text layer. The API can use OCR for scanned documents.
Multi-column PDFs
Newspapers, academic papers and reports often use two or more columns. Reading the text in the wrong order can produce something like:
Column 1, line 1
Column 2, line 1
Column 1, line 2
Column 2, line 2
rather than reading down the first column and then moving to the second.
The extraction process uses the PDF’s text positions to determine reading order, although particularly complicated layouts can still require some cleanup.
Tables
Tables are another common source of trouble because the PDF often stores the text without storing the table as an actual data structure.
The browser converter extracts the text from tables, while the API can preserve table structure when extracting supported documents.
Headers and footers
Page numbers, document titles and repeated headers can appear throughout the extracted content.
If you’re processing documents for RAG, you may want to remove repeated headers and footers before creating your embeddings. One simple approach is to look for lines that occur repeatedly across pages and remove them during preprocessing.
Characters with unusual positioning
Some PDFs don’t store words as words. Individual characters may be positioned separately on the page.
A naive extractor can turn Stepping into something closer to S t e p p i n g.
A good parser needs to reconstruct the words from the positions of those individual characters.
PDF to Markdown vs other tools
There are plenty of ways to get content out of a PDF. Which one makes sense depends on what you’re trying to do.
ChatGPT. Uploading a PDF to ChatGPT is convenient when you want to ask questions about one document. It’s less useful when you need a repeatable conversion process or want to feed hundreds of documents into your own pipeline.
Pandoc. Pandoc is excellent for converting between markup formats. It’s not primarily a PDF layout extraction tool, so it’s not necessarily the best choice when your starting point is a complex PDF.
Marker. Marker is an open-source document conversion tool designed to turn PDFs into formats including Markdown. It’s a good option if you want to run the conversion yourself and are comfortable managing the software and infrastructure.
Unstructured. Unstructured provides tools for ingesting and partitioning documents for downstream applications such as search and RAG. It’s more of a document processing framework than a simple PDF-to-Markdown converter.
The advantage of a browser-based converter is simplicity: upload a PDF, get Markdown, and you’re done. If you need to process documents programmatically, the API gives you the same basic workflow without having to maintain your own document extraction infrastructure.
Is PDF to Markdown private?
Text-based PDFs are processed in your browser, so the file doesn’t need to be uploaded to convert it.
For API requests, files are processed by the service rather than locally in your browser. API processing and data retention are subject to the service’s current policies.