Markdown as the Hub Format

The core idea: Markdown is the format Claude reads and writes best. For any serious document work, it pays to convert your inputs to markdown before giving them to Claude, and to draft in markdown before converting to your final format. This document explains why, and gives you the tools to do it.

Why markdown is Claude's native format

Claude can read PDFs, DOCX, XLSX, and other formats directly. But it processes all of them better when they are plain text — and markdown is the richest plain-text format.

The problem with native formats:

What markdown gives you:

The practical consequence: When you convert a PDF to markdown before giving it to Claude, you often get noticeably better extraction, more accurate identification of structure, and fewer errors — particularly for multi-column academic papers, documents with footnotes, or anything with a complex layout.

The hub model

Your sources                    Your outputs
(PDF, DOCX, XLSX, HTML...)      (DOCX, PDF, HTML...)
          │                              ▲
          ▼                              │
     [ markdown ]  ──── Claude ────  [ markdown ]
          ▲                              │
          │                              ▼
     to-markdown                   from-markdown
       tools                          tools

You do not always need both conversions. Reading and research tasks rarely need the output step. Writing and editing tasks often do.

TO markdown: converting your documents

markitdown — the general-purpose converter

What it handles: PDF, DOCX, XLSX, PPTX, HTML, images (with OCR), audio transcription Best for: Quick conversion of most common document types Quality: Good for most purposes; not the highest quality for complex PDF layouts

Install:

pip install "markitdown[pdf]"

Or with uv:

uv pip install "markitdown[pdf]"

Note: pip install markitdown (without [pdf]) installs successfully but silently fails on PDF files. Always use markitdown[pdf] — PDF conversion is the main reason most researchers install this tool.

Use:

markitdown document.pdf > document.md
markitdown paper.docx > paper.md
markitdown spreadsheet.xlsx > spreadsheet.md

The > means "save the output to this file". The result is a .md file ready for Claude.

Convert a whole folder:

for f in *.pdf; do markitdown "$f" > "${f%.pdf}.md"; done

Ask Claude to run this for you — you do not need to understand the syntax.

marker — higher quality for academic PDFs

What it handles: PDF only Best for: Multi-column academic papers, PDFs with complex layouts, documents with many footnotes, scanned PDFs with OCR Quality: Noticeably better than markitdown for difficult PDFs; slower

Install:

pip install marker-pdf

Use:

marker_single paper.pdf output_folder/

Output goes into output_folder/ as a markdown file. For a folder of PDFs:

marker papers/ output_folder/

When to use which tool for PDFs:

markitdown's real strength is non-PDF formats: DOCX, XLSX, PPTX, HTML, images with OCR, audio. For those it remains the simplest single-tool option. See A7.working-with-pdfs for the full PDF conversion comparison.

pandoc — for DOCX and structured formats

What it handles: DOCX, ODT, HTML, LaTeX, and many more → markdown Best for: Word documents, especially if you care about preserving heading structure cleanly Quality: Excellent for DOCX; the reference implementation for document conversion

Install: https://pandoc.org/installing.html Mac: brew install pandoc Windows: download the installer from pandoc.org

Use (DOCX to markdown):

pandoc paper.docx -o paper.md

Use (HTML to markdown):

pandoc page.html -o page.md

FROM markdown: producing final documents

Drafting in markdown and converting at the end is a clean workflow: Claude writes and revises markdown throughout, then one command produces the deliverable.

pandoc — markdown to DOCX

pandoc draft.md -o draft.docx

This produces a plain Word file. To apply your institution's or journal's styles:

pandoc draft.md --reference-doc=template.docx -o draft_formatted.docx

Where template.docx is a Word file with your styles defined. Pandoc maps heading levels, paragraph styles, etc. to the template. Ask Claude to run this command — you just need the template file.

Footnotes in markdown → Word footnotes:

This is a claim.^[This is the footnote text.]

Pandoc converts these to proper Word footnotes automatically.

Citations (if using Zotero or a .bib file):

pandoc draft.md --citeproc --bibliography=refs.bib -o draft.docx

Pandoc processes [@citation_key] markers and generates a formatted bibliography. Ask Claude to add citation markers while drafting; resolve them with pandoc at the end.

pandoc — markdown to PDF

Requires a LaTeX installation (larger, ~2GB):

pandoc draft.md -o draft.pdf

For most researchers, exporting to DOCX and then printing to PDF from Word is simpler.

markitdown / pandoc — markdown to other formats

pandoc draft.md -o draft.html          # web page
pandoc draft.md -o draft.odt           # OpenDocument (LibreOffice)
pandoc draft.md -t latex -o draft.tex  # LaTeX source

Setting these up as Claude Code skills

A Claude Code skill (custom slash command) is a reusable instruction you can invoke with /command-name. You define it once; it is available in every session.

Skills live in .claude/commands/ inside your project folder (or ~/.claude/commands/ for global skills available everywhere).

Global skills: always available

Create the folder if it does not exist:

mkdir -p ~/.claude/commands

/to-md — convert a file to markdown:

Create ~/.claude/commands/to-md.md:

Convert the file $ARGUMENTS to markdown.
Use markitdown if available, otherwise pandoc.
Save the output as the same filename with a .md extension.
Tell me the output filename when done.

Usage: /to-md paper.pdf → produces paper.md

/to-docx — convert markdown to Word:

Create ~/.claude/commands/to-docx.md:

Convert the markdown file $ARGUMENTS to a Word document using pandoc.
If a file called template.docx exists in the current folder, use it as the reference document.
Save as the same filename with a .docx extension.
Tell me the output filename when done.

Usage: /to-docx draft.md → produces draft.docx

/convert-folder — convert all PDFs in current folder to markdown:

Create ~/.claude/commands/convert-folder.md:

Convert all PDF files in the current folder to markdown using markitdown.
Save each as the same filename with a .md extension.
Report how many files were converted and list any that failed.

Usage: /convert-folder → converts every .pdf in the folder

Checking your skills are registered

Inside Claude Code:

/help

Your custom commands appear in the list alongside built-in commands.

Practical workflows using the hub model

Reading a batch of papers

# Convert first
/convert-folder

# Then work with clean markdown
> Read all .md files in this folder.
  For each: main argument, key method, relevance to network analysis.
  Output to reading_notes.md

Clean markdown input → Claude processes faster, misses less, uses less context.

Editing a draft

# Convert Word draft to markdown
/to-md chapter_draft.docx

# Work with Claude on the markdown
> Read chapter_draft.md
  Check the argument structure in section 2. Is the logic sound?
  Suggest improvements to paragraph 3, keeping my voice.

# When satisfied, convert back to Word
/to-docx chapter_draft.md

The Word document you hand to your supervisor is produced at the end, from clean markdown.

Processing archival documents

# High-quality conversion for complex PDFs
> Run: marker_single source_1241.pdf sources_md/

# Now extract
> Read sources_md/source_1241.md
  Extract all named persons with page references.
  Output to extractions/source_1241_persons.md

Summary: the habit to build

Step What you do
Inputs arrive (PDF, DOCX) Convert to markdown first
Work with Claude Everything in markdown
Output needed (DOCX, PDF) Convert from markdown at the end

You do not have to do this every time. For a single quick summary, hand Claude the PDF directly — it will work. But for any systematic work — processing a corpus, iterating on a draft, building a reading archive — the markdown hub model pays for itself quickly.

Related