mid_converter

Batch converter to Markdown using MarkItDown.
Inputs: html|htm, pdf, docx, doc, xlsx, pptx, txt as files or a folder.
Outputs: a <name>__md/ directory with .md files. Optional extraction of inlined data: images.

Features

• Single file or entire folder.
• Preserves data:image/*;base64,... inside Markdown or extracts them to files.
• Creates a deterministic output folder next to the input.
• Prints the absolute path to the result folder to stdout on success.
• Clear exit codes for automation.

Install

# Recommended: install with pipx
pipx install .

# Or with pip (in a venv or globally)
pip install .

Usage

mid-converter /absolute/path/to/file_or_folder [--assets inline|files]

• --assets inline (default): keep data: images embedded in Markdown.
• --assets files: extract base64 images to <stem>_assets/ and rewrite links.

Examples

Convert a single HTML:

python mark2md.py "C:\data\in.html" --assets files

Convert a folder of mixed files:

python mark2md.py "/home/user/reports" --assets inline

Output layout

For an input file report.html:

report__md/
└── report.md

With --assets files:

report__md/
├── report.md
└── report_assets/
    ├── img_001.png
    └── img_002.jpg

Supported inputs

• .html, .htm → special handling to retain/extract data: images
• .pdf, .docx, .doc, .xlsx, .pptx, .txt

Exit codes

• 0 success
• 2 input path not found
• 3 unsupported file type (single-file mode)
• 4 no supported files in folder
• 5 nothing converted (all failed)

Notes and limits

• MarkItDown quality depends on input type; complex PDFs or Office files may yield imperfect layout.
• For HTML with remote images (http/https), this tool does not download assets. Use MarkItDown CLI flags separately if needed.
• Tested on Python 3.9+.

Development

• One-file CLI: mark2md.py.
• No external configuration required.

License

MIT — see LICENSE.

Security

See SECURITY.md.

Contributing

See CONTRIBUTING.md.