doc-to-md

Convert documents into clean, faithful, structurally correct Markdown, saved in the source file's directory, with the same base name, and only the extension changed to .md.

The pipeline has two stages:

1. Deterministic stage (scripts/convert.sh): markitdown (extract) → postprocess.py (semantic cleanup) → markdownlint-cli2 --fix (lenient formatting rules). Always call the script for conversion and lint; it handles output paths, directory expansion, overwrite protection, cleanup, and lint config.
2. LLM refinement stage (you, on by default): markitdown flattens layout into text, losing heading levels, tables, multi-column reading order, and hyphenation/page breaks — the script cannot recover these. After the script runs, compare against the source to restore structure and strip extraction noise. See LLM refinement.

Workflow

1. Check tools

markitdown must be on PATH (command -v markitdown). If missing, tell the user to run pip install 'markitdown[all]', then stop. Lint runs via npx markdownlint-cli2. Without npx, the script skips lint and keeps the conversion — an acceptable fallback.

2. Overwrite protection

By default the script refuses to overwrite an existing .md and reports EXISTS\t<path> with exit code 3. Overwriting is the user's call, not the script's.