Microsoft MarkItDown for beginners: turn a PDF into reviewed Markdown for AI

The raw Markdown looked almost finished. All six source facts were there, but so were a duplicate title, a browser print header, a local file path, page numbers, and a page-break character. We removed that noise only after comparing the output with the PDF, then restored lightweight Markdown structure in a separate copy.

That is the workflow in this guide: PDF → raw Markdown → source check → reviewed Markdown. The original and the raw output remain untouched throughout.

Who this guide is for

This guide is for anyone who receives a brief, instruction, or report as a PDF and wants a transparent text file before the content enters summarization, search, or another AI workflow.

We use a fictional two-page AI pilot brief. The PDF contains selectable text. That matters because the standard PDF path in this guide is not OCR for scanned pages.

What you will have when you finish

You will have:

• The original PDF, unchanged;
• Untouched raw Markdown from the converter;
• Six source anchors checked against the PDF;
• A separate reviewed Markdown file;
• A short conversion receipt.

What Microsoft MarkItDown is

Microsoft MarkItDown is an open-source Python utility that converts files to Markdown for language models and other text-analysis workflows. Markdown is readable plain text with lightweight structure for headings and lists.

Microsoft also says the output is designed for text analysis rather than faithful reproduction of a document's visual layout. Treat the conversion as a reviewable intermediate format, not a perfect copy.

Source: Microsoft MarkItDown README.

At publication, MarkItDown 0.1.7 was the current PyPI release. The package requires Python 3.10 or later and provides a separate extra for PDF support.

Source: MarkItDown on PyPI.

Before you start: choose a PDF with selectable text

Place the PDF in a dedicated working folder and confirm that you can select and copy its text. Then write down six facts that must survive conversion. Our test used:

1. title;
2. date;
3. owner;
4. the complete goal sentence;
5. the stop rule;
6. the complete approved-result sentence.

Use a file you are allowed to process and keep the source unchanged. A dedicated folder makes the workflow easier to review, but it is not a technical sandbox. MarkItDown retains the normal file and network privileges of its process.

Step 1: install only the PDF support

The commands below are the path we tested in a Linux/macOS-style shell. First create an isolated Python environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'markitdown[pdf]'
markitdown --version

The PDF extra installs the dependencies needed for this file type. This guide does not use the broader all installation, Azure services, or OCR plugins.

Step 2: create untouched raw Markdown

Run the conversion with an explicit output file:

markitdown ai-pilot-brief.pdf -o ai-pilot-brief-raw.md

-o sets the output destination. The word raw marks this as converter output that has not been approved. Do not edit it before comparing it with the source.

Our test used the PDF's existing text layer. MarkItDown's built-in PDF converter relies on pdfplumber and pdfminer.six, so a scanned image page needs a separate OCR path.

Source: MarkItDown PDF converter.

Step 3: compare the source anchors before cleanup

Open the PDF and raw Markdown side by side. Use this review card:

PDF → Markdown review
[ ] The title appears in the reviewed file
[ ] The date and owner match the PDF
[ ] The goal sentence is complete
[ ] The stop rule is unchanged
[ ] The approved-result sentence is complete
[ ] The reading order still makes sense
[ ] Headers, footers, page numbers, and file paths are marked as noise
[ ] Missing, duplicated, or uncertain text is recorded

The publication-day check behind this guide read the PDF text layer with pdftotext, compared six predefined anchors with both the raw and reviewed files, and confirmed the same order across all three. That check says nothing about every other PDF. It records what happened in this bounded test.

Step 4: create a separate reviewed copy

Copy the raw output to a new filename:

cp ai-pilot-brief-raw.md ai-pilot-brief-reviewed.md

In our test file, we removed the duplicate title, browser date line, local file:/// line, page counters, and page-break character. We also restored lightweight Markdown structure for headings and lists without rewriting the document's factual wording.

Other PDFs will fail differently. Remove only material you have checked against the source. If a paragraph is missing or the reading order is unclear, record it as an open question in the receipt instead of hiding it with a quick rewrite.

Step 5: save a conversion receipt

The receipt can stay compact:

Input: ai-pilot-brief.pdf
Pages: 2
Source anchors checked: title, date, owner, goal, stop rule, approved result
Raw output preserved: yes
Conversion noise reviewed: yes
Reviewed file: ai-pilot-brief-reviewed.md
Open questions: none in this test

Add the MarkItDown version and review date if the file may be reused later. That makes its origin easier to understand.

Common PDF-to-Markdown mistakes

• Treating command success as content approval.
• Using a scanned PDF when the workflow has no OCR step.
• Deleting repeated-looking text before protecting the source anchors.
• Passing raw Markdown onward without checking reading order, omissions, and page residue.

What to do with the reviewed file next

The reviewed Markdown can now become transparent input for summarization, search, a knowledge base, or a controlled agent workflow. Keep the source path and review date with the file.

If this document intake repeats, Hammer can help build a governed workflow with scoped access, review points, and run logs. Learn more about Tool Forge.