Document To Markdown

Workflow

1. Keep the original document in local storage such as downloads/ or another non-source location.
2. Run scripts/convert_document.py on the local file.
3. Write the Markdown output under ignored storage such as artifacts/markdownified/ unless the user wants a different location.
4. Pass --source-url whenever the local document was downloaded from a public source.
5. Use the generated Markdown as a reference copy; do not treat it as a substitute for the original file when provenance or formatting disputes matter.

Output Contract

The converter prepends YAML frontmatter with:

• source_file
• source_url when provided
• converted_at_utc
• converter

Keep that header intact so later dataset work can recover provenance and conversion timing.

Script

Use scripts/convert_document.py for deterministic conversion. It:

• accepts one local input file
• writes Markdown either to --output or a derived file path under --output-dir
• creates parent directories as needed
• refuses to overwrite existing files unless --force is set

If the document type is unsupported or conversion quality is poor, keep the original file and note the limitation rather than silently rewriting the Markdown by hand.

If conversion problems recur and a better structured-document pipeline is needed, consider evaluating Docling as a heavier fallback. It is not the default here because the dependency stack is much larger than the current MarkItDown-based path.