Practical Workflows

All workflows target MarkItDown 0.1.6 and use .markdown, not the legacy .text_content alias.

1. One Trusted Local Document

from hashlib import sha256
from pathlib import Path

from markitdown import MarkItDown

source = Path("protocol.docx").resolve(strict=True)
output = Path("protocol.md")

result = MarkItDown().convert_local(source)
output.write_text(result.markdown, encoding="utf-8")

provenance = {
    "source": source.name,
    "sha256": sha256(source.read_bytes()).hexdigest(),
    "title": result.title,
    "output": str(output),
}
print(provenance)

For very large files, compute the hash incrementally rather than loading the source again.

2. Binary Upload

Validate size and type before conversion. Use BytesIO plus explicit hints:

from io import BytesIO

from markitdown import MarkItDown, StreamInfo


def convert_pdf_upload(payload: bytes, filename: str) -> str:
    max_bytes = 25 * 1024 * 1024
    if len(payload) > max_bytes:
        raise ValueError("PDF exceeds the 25 MiB conversion limit")
    if not payload.startswith(b"%PDF-"):
        raise ValueError("Payload does not have a PDF signature")

    result = MarkItDown().convert_stream(
        BytesIO(payload),
        stream_info=StreamInfo(
            extension=".pdf",
            mimetype="application/pdf",
            filename=filename,
        ),
    )
    return result.markdown

Signature checks are only one validation layer; they do not make the parser sandboxed.

3. Batch Directory Conversion

python scripts/batch_convert.py inputs/ outputs/ \
  --recursive \
  --extensions .pdf .docx .pptx .xlsx .csv .html \
  --manifest outputs/manifest.json

Properties:

• Local paths only
• Symlinks skipped
• Deterministic path ordering
• Relative directories preserved
• Output name retains the source suffix, e.g. paper.pdf.md
• Existing output skipped unless --overwrite
• Plugins off unless --plugins
• Nonzero exit when a conversion fails

Retry failed files after installing the missing format extra:

uv pip install "markitdown[pdf,docx,pptx,xlsx]==0.1.6"
python scripts/batch_convert.py inputs/ outputs/ --recursive --overwrite

Use a fresh output directory when comparing converter versions.

4. Literature Collection

Input naming convention:

Author_Year_Title.pdf

Convert and build indexes:

python scripts/convert_literature.py papers/ literature/ \
  --recursive \
  --create-index

Organize by inferred year:

python scripts/convert_literature.py papers/ literature/ \
  --recursive \
  --organize-by-year \
  --create-index

Each output contains provenance front matter:

---
title: "Example title"
author: "Smith"
year: "2025"
source: "incoming/Smith_2025_Example_Title.pdf"
converted_at: "2026-07-23T17:00:00+00:00"
markitdown_version: "0.1.6"
---

The helper also writes catalog.json and INDEX.md when --create-index is requested. Metadata inferred from a filename is a convenience, not authoritative bibliographic metadata.

5. RAG Ingestion

Recommended sequence:

1. Validate and hash the source.
2. Convert with a pinned package/plugin version.
3. Keep source metadata separate from converted text.
4. Check non-empty output and expected section markers.
5. Sanitize active HTML and unsafe links if Markdown will be rendered.
6. Chunk by semantic headings with overlap.
7. Store source/hash/converter/page-or-section provenance with every chunk.
8. Mark chunks as untrusted source content in the retrieval prompt.
9. Retain the original source for verification.

Example conversion envelope:

from dataclasses import asdict, dataclass
from hashlib import sha256
from importlib.metadata import version
from pathlib import Path

from markitdown import MarkItDown


@dataclass(frozen=True)
class ConvertedDocument:
    source_name: str
    source_sha256: str
    converter_version: str
    title: str | None
    markdown: str


def convert_for_ingestion(path: Path) -> ConvertedDocument:
    path = path.resolve(strict=True)
    digest = sha256(path.read_bytes()).hexdigest()
    result = MarkItDown().convert_local(path)
    if not result.markdown.strip():
        raise ValueError(f"Conversion produced no text: {path.name}")

    return ConvertedDocument(
        source_name=path.name,
        source_sha256=digest,
        converter_version=version("markitdown"),
        title=result.title,
        markdown=result.markdown,
    )

Do not treat Markdown line numbers as stable page citations. MarkItDown does not expose PDF page coordinates.

6. Mixed-Format Study Folder

Use a two-pass workflow:

Pass A: inventory

• Count files by extension and byte size.
• Detect duplicates by content hash.
• Exclude temporary, lock, and hidden files.
• Identify encrypted/unsupported inputs.
• Classify which files require external OCR/cloud processing.

Pass B: convert

• Use local built-ins first.
• Route only failed scanned/complex files to an approved OCR/cloud path.
• Record the selected mode per file.
• Compare file count, failure count, and output count.

This minimizes cost and external data transfer.

7. Spreadsheet Orientation, Then Structured Analysis

Use MarkItDown to understand workbook organization:

from markitdown import MarkItDown

preview = MarkItDown().convert_local("assay-results.xlsx").markdown
print(preview)

Then use a spreadsheet/dataframe library for calculations:

• Inspect formulas and cached values explicitly.
• Select the authoritative sheet/range.
• Preserve data types.
• Validate merged cells and hidden rows.

Do not parse a scientific numeric dataset back out of Markdown when the original workbook is available.

8. Presentation Review

from markitdown import MarkItDown

result = MarkItDown().convert_local("lab-meeting.pptx")

Review:

• Slide boundaries
• Title hierarchy
• Speaker notes
• Text in charts/images
• Claims encoded only by color/position

If images carry essential meaning, add an approved vision description or OCR pass and label generated text as model-derived.

9. Scanned-PDF Escalation

1. Try built-in PDF extraction.
2. Detect unexpectedly short/empty output relative to page/file size.
3. Confirm the source is scanned by visual inspection.
4. Choose:
   • Local OCR/layout parser for restricted data
   • markitdown-ocr for approved vision-provider processing
   • Document Intelligence for Azure layout/OCR
   • Content Understanding for structured fields/multimodal processing
5. Validate a page sample and record the selected service/model/analyzer.

Do not automatically send failed local conversions to a cloud service.

10. Application-Controlled Remote Resource

The application—not MarkItDown—should:

• Validate destination and every redirect
• Enforce time and byte limits
• Restrict MIME types
• Apply authentication safely
• Produce a bounded requests.Response

Then:

result = MarkItDown().convert_response(validated_response)

See security.md for the complete SSRF policy. A simple scheme check is not sufficient.

11. Deterministic Regression Corpus

Keep a small, redistributable corpus covering:

• Text-native and scanned PDFs
• DOCX headings/tables/equations
• PPTX notes/grouped shapes
• XLSX multiple sheets/merged cells
• CSV quoted fields and Unicode
• HTML links/lists/tables
• EPUB chapters
• JPEG/PNG metadata

For each fixture, assert:

• Conversion succeeds or fails with the expected category.
• Required headings/sentinel text are present.
• No source is unexpectedly routed to network/cloud.
• Output is UTF-8 and below a reasonable size.
• Package/plugin versions are recorded.

Avoid asserting a full byte-for-byte Markdown snapshot unless exact formatting stability is required; semantic assertions are less brittle.

12. Conversion Quality Report

Track per file:

• Source identifier and hash
• Bytes and extension
• Converter mode
• MarkItDown/plugin version
• Output characters/lines
• Optional title
• Warning/failure category
• Manual validation status
• External provider/analyzer, if any

The bundled batch manifest provides a baseline for these records.