Stop feeding Claude PDFs. Use Markdown instead.

If you have spent any time working with Claude on real documents, you will have noticed something. Paste in a PDF, a Word doc, or a PowerPoint export, and the conversation gets noisier. The model has to work through encoding artefacts, repeated headers and footers, garbled tables, and metadata clutter before it gets to the content you actually care about. You are paying for all of that in both cost and quality.

The fix is simple, and most people skip it: convert your documents to Markdown first.

Why format matters more than most people realise

Language models process text as tokens. Tokens are not words, exactly. They are chunks of text, typically a few characters each, that the model uses as its unit of thinking. Every token in your context window is something the model has to process, attend to, and reason about.

A well-formatted PDF looks clean on screen. Extracted as raw text, it often looks like this: repeated column headers, page numbers embedded mid-sentence, footnotes scattered through the body, whitespace characters everywhere. All of that becomes tokens. None of it helps the model understand your document.

Markdown is different. It is almost entirely content, with just enough structure to signal what things are: headings, lists, tables, links, emphasis. No wasted characters. No formatting noise. And critically, large language models were trained on enormous amounts of Markdown. It is one of the most natural input formats for them. They do not just tolerate it; they think in it.

The practical difference is real. The same report converted to Markdown instead of extracted directly from PDF can use noticeably fewer tokens to represent the same information, and the model’s comprehension of the structure is sharper. Headers become actual headings. Tables become parseable grids. Bullet points become lists, not lines starting with hyphens.

What MarkItDown does

Microsoft’s open-source MarkItDown utility handles the conversion automatically. It takes a file in almost any format and produces clean Markdown. The list of supported inputs covers most of what you will encounter in a working environment:

  • PDF
  • Word documents (DOCX)
  • PowerPoint presentations (PPTX)
  • Excel spreadsheets (XLSX)
  • Images, with EXIF metadata and optional OCR
  • HTML pages
  • CSV, JSON, and XML files
  • Audio files, with optional speech transcription
  • YouTube URLs, pulling from available transcripts
  • EPub ebooks

For most office documents, it works without any external service or API key. You run it locally, it converts, done.

How to install it

MarkItDown requires Python 3.10 or higher. The cleanest way to install it as a command-line tool is with pipx, which handles the Python environment for you and makes the markitdown command available system-wide without interfering with anything else.

Step 1: Check your Python version

python3 --version

If you get 3.10 or above, you are good. If you are on an older version, install a newer one first via Homebrew on Mac:

brew install python@3.12

Step 2: Install pipx

If you do not already have pipx:

brew install pipx
pipx ensurepath

Then open a new terminal window so the PATH change takes effect.

Step 3: Install MarkItDown

pipx install 'markitdown[all]'

The [all] flag pulls in optional dependencies for all supported file types. If you want a lighter install and only need specific formats, you can be selective: markitdown[pdf,docx,pptx] for just the office formats, for example.

Verify it worked:

markitdown --version

You should see markitdown 0.0.2 or similar.

Using it

The basic usage is straightforward. Point it at a file and redirect the output:

markitdown report.pdf > report.md

Or use the -o flag to write to a file directly:

markitdown report.pdf -o report.md

It also accepts piped input, which is useful for scripting:

cat report.pdf | markitdown > report.md

Once you have the Markdown file, you can paste it directly into Claude, attach it, or include it in any workflow that benefits from clean, structured text.

Wiring it into Claude Code with a slash command

If you are using Claude Code, either through the CLI or through the Claude desktop app’s built-in code mode, there is a cleaner option than converting manually and then pasting. You can create a /convert slash command that runs the conversion and drops the result directly into the conversation.

Claude Code reads custom commands from files in ~/.claude/commands/. Create that directory if it does not exist, then create a file called convert.md inside it:

mkdir -p ~/.claude/commands

Then create ~/.claude/commands/convert.md with the following content:

---
description: Convert a file to Markdown using MarkItDown
argument-hint: <file-path>
allowed-tools: [Bash, Read]
---

Convert the file at `$ARGUMENTS` to Markdown using markitdown:

1. Confirm the file exists. If not, tell the user and stop.
2. Run: ~/.local/bin/markitdown "$ARGUMENTS"
3. If it fails, report the error. If it succeeds, present the Markdown
   and ask the user what they would like to do with it.

Once that file exists, you can use /convert in any Claude Code session:

/convert ~/Downloads/board-deck.pptx
/convert report.pdf
/convert https://example.com/page

The conversion runs locally, the Markdown lands in the conversation, and you can immediately ask Claude to summarise, analyse, or act on it without leaving the session.

This works in both the CLI version of Claude Code and the code mode inside Claude Desktop. It does not work in the standard conversation interface in Claude Desktop, or on claude.ai, as neither of those surfaces has access to local commands.

A note on where you are in your tooling: a lot of people are currently using Claude Code through the desktop app without having made the jump to the full command-line version. That is a perfectly reasonable place to be, and the slash command above works there. There are real advantages to moving to the CLI eventually, and real advantages to the CLI over the desktop app’s code mode, but that is a longer conversation for another post.

The broader principle

This is an example of a larger pattern that applies across AI work: small changes to inputs can have outsized effects on output quality. The model is not magic. It is working with what you give it. Give it clean signal and you get better reasoning. Give it noise and you get worse reasoning, at higher cost.

Markdown is not special because it is fashionable. It is useful because it is efficient, human-readable, and well-aligned with how language models process information. Converting your documents before sharing them is a low-effort habit that compounds quickly, especially if you are doing this kind of work regularly.

The tool is free, takes five minutes to install, and the difference is immediate.

This post is part of a series on AI fluency: the practical habits and tool choices that compound over time. Coming up: why Claude Code’s desktop mode is worth switching to over standard chat, and why the full CLI is worth the extra step after that.