markitdown, explained for people who don't code.

elisabeth hitz · july 14, 2026 · 4 min read

markitdown is a free tool from microsoft that takes a messy file, a pdf, a word doc, a spreadsheet, and turns it into clean markdown that ai reads well, and you do not need to be a coder to use it. it exists because the format your file is saved in changes how well the model understands it. a pdf hides the structure. markdown puts it back in plain text the model can follow.

if you have ever pasted a report into claude and gotten a vague, confused answer, the file was probably the problem, not the model. that is the whole idea behind markdown vs pdf for claude, and markitdown is one of the free ways to close that gap.

what is markitdown, really?

it is a small open-source program microsoft released to convert common office and document files into markdown. markdown is just text with light structure: a heading is a line starting with a hash, a list is lines starting with dashes, a table is rows separated by pipes. no fancy formatting, no hidden layout, nothing for the model to misread. markitdown reads your file and rewrites its contents in that plain, structured shape.

it is free, it is maintained by microsoft, and it does one job. it is not an ai itself. it does not summarize or rewrite your content. it just changes the container so the actual ai you use afterward gets a clean input.

what it converts

markitdown handles most of the file types that pile up in a normal business:

• pdf reports, contracts, one-pagers, downloaded specs
• word documents, the .docx files you write proposals and policies in
• powerpoint decks, pulling the text off each slide
• excel spreadsheets, turning rows and columns into markdown tables
• images and other formats, with varying results depending on what is inside

the common thread is documents that carry real text. it lines up that text and hands you a tidy markdown version, headings intact, lists intact, tables laid out in a shape the model can actually parse.

the non-scary ways to run it

here is the honest part. markitdown is technically a command-line tool, which means the standard way to run it involves a terminal, and for a lot of people that is a hard stop. you have options that skip the fear entirely:

• ask a technical friend or teammate to run it once. it is a thirty second job for anyone comfortable with a terminal, and the output is a plain file they can send you.
• use claude as your converter instead. if the terminal is a wall, you do not need markitdown at all. open claude, attach the file, and say: convert this to clean markdown, keep every heading, list and table, return only the markdown. copy the result into a file and you are done. it is the same outcome without touching code, and it is one of the three free ways to convert a pdf to markdown.

the tool is worth knowing about because it is free and reliable and it comes from microsoft, so it will be around. but the goal is clean markdown, and there is more than one road there. do not let the terminal talk you out of the whole thing.

what good output looks like

once you have the markdown, glance at it before you trust it. good output has clear headings where the original had headings, lists that stayed as lists, and tables that still line up in rows. bad output is a wall of run-on text with the structure flattened out, or numbers that jumped columns. if it looks like the second one, the source file was probably a scan, which brings us to the one real limit.

its honest limit: scanned docs

markitdown reads text that is actually text. it cannot read a scan or a photo of a page, because to the computer that is just a picture with no words in it. those files need optical character recognition first, a separate step that turns the image into real characters. if your pdf is a scan (you cannot select the words with your cursor), markitdown will come back with little or nothing, and that is expected, not a bug.

this is the same discipline behind everything on this blog: the reason your ai is not working is usually the input, not the intelligence. markitdown is one clean, free way to fix the input before you ever ask the model to think.

faq

is markitdown free?

yes. it is free and open-source, released by microsoft. there is no license to buy and no subscription to run it.

do i have to use the terminal?

no. the tool itself is command-line, but you can have a technical person run it once, or skip it entirely and let claude do the conversion inside a normal chat. the terminal is optional, the clean markdown is the point.

will markitdown work on a scanned pdf?

not well. it reads real text, and a scan is an image with no text layer. you would need optical character recognition first to turn the picture into characters it can convert.