Pandoc cannot convert a PDF directly to Markdown because it has no PDF input reader; the PDF must first become an editable source format that Pandoc can read.
PDF and Markdown describe different structures. A PDF presents positioned page content and usually does not retain the source application's heading styles, while Markdown marks headings, paragraphs, lists, links, code, and tables. Pandoc can translate between recognized document formats, and it can output a PDF, but it cannot import one as input.
A practical workflow therefore has two stages: recover editable content and structure from the PDF, then use Pandoc to turn that intermediate file into Markdown. An original DOCX removes the first stage, while an image-only PDF requires OCR.
Why a direct PDF command fails
Commands such as pandoc input.pdf -f pdf -t gfm -o output.md do not work because the -f option selects the input format, and PDF is not a supported Pandoc input. This is an input-format limitation rather than a damaged-file problem.
Text extraction introduces separate challenges. A text-based PDF may yield clean words while flattening columns, running text, table cells, or headings into ordinary lines. A scanned PDF adds recognition errors to those structural problems. OCR can make characters available, but it does not reliably determine which text is a title, which label belongs with a value, or which cells form a table. A structured intermediate file or an editorial pass is still needed.
Choose the most reliable source
Choose the conversion route based on the file you actually have:
| Available source | First stage | Pandoc input | Expected result |
|---|---|---|---|
| Original DOCX | None | DOCX | Best chance of retaining explicit headings, lists, and tables |
| Text-based PDF | Extract to DOCX or HTML | DOCX or HTML | Reading order and hierarchy depend on the extractor |
| Scanned PDF | OCR to DOCX or HTML | DOCX or HTML | Expect to correct OCR errors and incomplete structure |
| Simple prose PDF | Extract to plain text | Text | Useful for paragraphs, but the original hierarchy is absent |
An original DOCX is preferable because its heading and table structure may already be explicit. For PDF-only material, DOCX or HTML gives Pandoc more semantic information than plain text. If you need a separate walkthrough of that intermediate-file approach, see Convert PDF to Markdown via DOCX.
Convert PDF to Markdown with Pandoc through an editable source
- Confirm that Pandoc is available. Install Pandoc for your operating system, open a terminal in the folder containing your files, and run pandoc --version. If the command is not recognized, complete the installation or correct the executable path before continuing.
- Create an editable intermediate file. Use the original DOCX whenever one exists. Otherwise, run the PDF through an extractor that produces DOCX or HTML. For a text-based PDF, one possible HTML route is pdftohtml -stdout input.pdf > extracted.html. For an image-only PDF, use OCR and export the result to DOCX or HTML rather than another PDF.
- Inspect and repair the intermediate file. Open it in a text editor, document editor, or browser. Check the reading order, remove extraction artifacts, and convert genuine section titles into HTML heading elements or Word Heading 1–6 styles. Flatten or rebuild tables that contain merged cells, nested tables, or uneven rows.
- Run Pandoc on the intermediate file. For DOCX, use pandoc source.docx -f docx -t gfm --wrap=none -o output.md. For HTML, use pandoc source.html -f html -t gfm --wrap=none -o output.md. The explicit format flags prevent Pandoc from having to infer the input type.
- Compare the result with the PDF. Open output.md in a Markdown editor and check every heading, table, list, link, code block, and paragraph against the source pages. Correct extraction mistakes in the Markdown or return to the intermediate file when repairing the structure there is easier.
- Finalize before publishing. Remove temporary notes and broken artifacts, then save the reviewed file for your repository, CMS, documentation site, note application, or static-site workflow.
Pandoc commands for common intermediate formats
The same basic pattern works with several source types: name the input, select its format with -f, select GitHub-Flavored Markdown with -t gfm, and write the result with -o.
- DOCX: pandoc source.docx -f docx -t gfm --wrap=none -o output.md
- HTML: pandoc source.html -f html -t gfm --wrap=none -o output.md
- Plain text: pandoc extracted.txt -f markdown -t gfm --wrap=none -o output.md
The --wrap=none option prevents Pandoc from wrapping long Markdown lines. If the destination requires strict CommonMark rather than GitHub-Flavored Markdown, replace gfm with commonmark. Plain text provides no reliable heading hierarchy, so add Markdown heading markers or use a structured intermediate file before conversion.
Rebuild structure before Pandoc sees it
PDF extraction can identify words and approximate positions without preserving document semantics. A large, bold line may be a title, a label, or ordinary emphasized text. To make the Pandoc result predictable, use explicit HTML heading elements such as h1 through h6, or apply Word Heading 1 through Heading 6 styles in a DOCX. Do not rely on font size, bold text, or visual prominence alone.
Basic Markdown tables also work best when the source is rectangular. Keep one header row and a consistent number of cells in each row. Merged cells, nested tables, and uneven rows cannot be represented faithfully in a simple pipe table, so rebuild them as separate tables or readable text before running Pandoc. Correcting structure in the intermediate file usually produces a cleaner result than repeatedly repairing the final Markdown.
Run OCR only when the pages require it
OCR is necessary when the PDF contains scanned page images without selectable text. A PDF that already exposes selectable characters does not automatically need OCR, and running OCR over clean text can introduce errors rather than improve it. For a scanned document, OCR to DOCX or HTML, inspect the result, and then pass that file to Pandoc.
OCR output still requires review. Check names, numbers, punctuation, line order, column boundaries, and table labels. Optical recognition does not restore the original Word heading styles, hyperlinks, comments, tracked changes, or other interactive structures. If a page contains complex tables or an unreliable reading order, manual reconstruction may be more accurate than forcing the extracted content into Markdown.
Use a local DOCX shortcut after source recovery
If a DOCX version is available and you want a browser-based structural draft without installing Pandoc, the DOCX to Markdown Converter creates a Markdown file from one .docx document. It is not a PDF reader, so use it only when the original DOCX exists or after another process has produced a DOCX copy.
Supported browser workflow
- Choose one .docx Word document from your device.
- Review the local Markdown preview, paying particular attention to the heading and table output.
- Download the .md file and make any editorial adjustments in your Markdown editor.
The converter processes the document locally without uploading it. Only explicit Word Heading 1–6 paragraph styles become Markdown headings from number sign through six number signs. Ordinary paragraphs remain text, and custom styles are not promoted to headings. Simple rectangular tables become pipe tables with the first row as the header; merged, nested, or uneven tables fall back to readable tab-separated text. Tabs and line breaks remain visible instead of being silently removed.
This is deliberately a structural conversion, not a visual Word replica. Fonts, spacing, columns, page numbers, images, charts, comments, tracked changes, fields, citations, text boxes, and theme styles are outside its contract. Password-protected, damaged, unsupported, oversized, or malformed packages are rejected or stop the conversion rather than producing a misleading result. The downloadable Markdown is a starting draft, so review it before publishing.
Check the output before publishing
A successful command proves that Pandoc read the intermediate file, not that every PDF detail was recovered. Review the result systematically:
- Headings: Confirm that each one represents a real section and that its level matches the document's hierarchy.
- Tables: Check header rows, cell alignment, and whether complex source tables were flattened correctly.
- Lists and links: Repair numbering that depends on Word-specific behavior and verify every destination.
- Reading order: Compare multi-column passages with the PDF, especially after OCR or HTML extraction.
- Characters: Look for OCR errors, broken symbols, misplaced punctuation, and damaged whitespace.
- Visual elements: Account separately for images, charts, footnotes, and other content that a text-focused conversion may omit.
Keep the original PDF beside the Markdown during review. The goal is not to make the converted file look identical on screen; it is to preserve useful content and structure for the destination while making every unavoidable loss visible.