Turn PDFs and Word files into notes Claude and ChatGPT can read, with MarkItDown
A step-by-step guide to MarkItDown, Microsoft's free open-source tool that turns PDFs, Word, PowerPoint and Excel files into plain Markdown text. Written for people who have never opened Terminal. Mac first.
Start here
How to use this canvas
- Go top to bottom. Grey blocks are commands: copy one, paste it into Terminal, press Return.
- You only do "Set up on a Mac" one time. After that it's just "Use it".
- If something goes wrong, see "If it doesn't work".
What MarkItDown is
- A small free tool from Microsoft, open source under the MIT license, about 190k stars on GitHub (2026-10).
- It reads PDF, Word, PowerPoint, Excel, HTML, CSV, EPub and more, and writes the text out as Markdown: plain text that keeps headings, lists and tables.
- Its README says it's made for feeding documents to AI, not for pretty copies for people to read.
- put·here is not affiliated with Microsoft or MarkItDown.
- Source: microsoft/markitdown README (official) https://github.com/microsoft/markitdown
Why bother, when Claude and ChatGPT already take PDFs
- One Markdown file works with any AI, now and later, and you can read and fix it yourself.
- It's much smaller than the original, so more of your material fits in one chat.
- You can keep the .md files next to your notes, for example in a put·here canvas folder, and reuse them.
- What you'll end with: a .md file next to each document you convert.
Set up on a Mac
Open Terminal
- Press Command and Space, type Terminal, press Return.
- A window with a blinking cursor opens. That's where the grey blocks go.
Check your Python, install it only if needed
Paste this and press Return:
python3 --version
- If it says Python 3.10, 3.11, 3.12, 3.13 or 3.14, you're set. Skip to the next card.
- If it says an older number, says the command isn't found, or a window pops up offering to install developer tools: close that window, go to python.org/downloads/macos and download the installer for the newest Python 3.14 (in 2026-10 that's 3.14.10). Open the .pkg and click through; it asks for your Mac password. Then close and reopen Terminal and check again.
- Why not 3.15: the MarkItDown README lists Python 3.10 to 3.14.
- Tried on a Mac (macOS 15, Python 3.12 already installed), 2026-10: the check showed 3.12, so we skipped the install. We haven't run the python.org installer on a fresh Mac.
- Source: python.org (official) https://www.python.org/downloads/macos/
Make a small folder for MarkItDown and install it
Paste these two lines one at a time, pressing Return after each. The first makes a folder called markitdown in your home folder; the second installs MarkItDown inside it. The second can take a minute.
python3 -m venv ~/markitdown
~/markitdown/bin/pip install 'markitdown[all]'
- Everything lives in that one folder. To remove MarkItDown later, just delete the markitdown folder in your home folder.
- At the end you may see a notice that a new version of pip is available. You can ignore it.
- Tried on a Mac (macOS 15), 2026-10: the install took about 15 seconds and finished without errors; MarkItDown version 0.1.9. Also tried on Linux.
Use it
Convert one file
Type the start of the line below, then drag your file from Finder into the Terminal window (it fills in the file's path), then type the rest and press Return.
~/markitdown/bin/markitdown DRAG-YOUR-FILE-HERE -o ~/Desktop/converted.md
- A file called converted.md appears on your Desktop.
- Tried on a Mac, 2026-10: a made-up Word file with a heading, a paragraph and a table came out with the heading, the paragraph and the table in Markdown.
Convert a whole folder
Put the files in a folder on your Desktop called to-convert, then paste:
for f in ~/Desktop/to-convert/*; do case "$f" in *.md) continue;; esac; ~/markitdown/bin/markitdown "$f" -o "${f%.*}.md"; done- Each file gets a .md twin with the same name, in the same folder.
- Files that are already .md are skipped, so you can add new files and run it again.
- Tried on a Mac, 2026-11: a folder with a Word file, a PDF and a scanned PDF gave three .md files next to them; the scanned one was empty (see "What it won't do"). Ran the same line a second time: still three .md files, nothing converted twice.
Hand it to Claude or ChatGPT
Open the .md file, copy everything, and paste it into the prompt below.
Here is a document I converted to Markdown:
<document>
Paste the Markdown here.
</document>
First list the 5 most important points, each with a short quote from the document. Then tell me what's missing or unclear in it.
- Asking for quotes keeps the answer tied to the document; Anthropic's prompting guide suggests it for long material.
Honest bit
What it won't do
- Scanned PDFs (photos of pages) come out empty, because there's no text in them to read. Tried on a Mac, 2026-10: a PDF made of one picture of text gave an empty file.
- Layout, colours and fonts are dropped. Tables survive; complex ones can come out messy.
- Plain file conversion runs on your computer. Some optional features, like YouTube links or Microsoft's Azure services, go online, and the Azure ones cost money.
- Windows works too, but the commands are different; this canvas covers Mac only.
If it doesn't work
- "command not found: python3": the Python installer didn't finish. Run it again (see "Check your Python, install it only if needed"), then close and reopen Terminal.
- "No such file or directory": the path is wrong. Drag the file into Terminal again instead of typing it.
- A file name with spaces: dragging handles this for you. If you type a path, put it in quotes.
- The install says Python is too new: install 3.14 (see "Check your Python, install it only if needed"), then delete the markitdown folder and redo "Make a small folder for MarkItDown and install it".
Try it, and sources
Convert three documents you keep going back to
Pick three PDFs or Word files you reread often, convert them (see "Convert a whole folder"), and ask Claude or ChatGPT one question about them with the prompt in "Hand it to Claude or ChatGPT".
Sources
