Why provenance breaks the moment you convert at scale
Converting one or two files by hand keeps their origin in your head. Converting three hundred at once erases it. Files get renamed, deduplicated with numeric suffixes, mixed with exports from other formats, and re-converted after a parser update. When a colleague asks whether a policy document is the latest version, or an audit demands the original source, there is no reliable path back — only a shared drive and guesswork. The problem compounds because the file name is the only thread most workflows keep, and a single rename or folder move snaps it.
What the front matter block gives you
Every MarkItDown Online export starts with a YAML block between --- markers recording the original file name, the source format (PDF, DOCX, XLSX, PPTX, HTML, image, or audio), the page or sheet count where applicable, and the UTC conversion timestamp. Body content begins right after the closing --- line, so renderers that ignore front matter display the document unchanged. Because the record lives inside the file, it survives copying, git commits, ZIP round trips, and CMS imports — everywhere a bare file name would be lost. Each field earns its place: the source file name lets you locate and re-convert the original, the format field makes filtering a mixed batch trivial, the page count supports completeness checks, and the timestamp powers staleness detection.
Four workflows that run on front matter
1) Staleness sweeps: compare each conversion timestamp against the source's last-modified time and flag the files worth re-converting before anyone reads outdated content. 2) Selective re-conversion: after a parser upgrade, filter by the format field and re-run only the affected files — every XLSX after a table fix, for instance — instead of the whole library. 3) Audit trails: for regulated content, trace each published page back to the exact source file and the moment it was converted. 4) Completeness checks: reconcile the recorded page or sheet count against the section structure of the body to catch truncated conversions early. A small script can run all four checks across an entire repository in seconds, because the data it needs is already inside each file.
Rules that keep front matter trustworthy
Treat the block as generated data: never hand-edit its values. Keep it at the very top of the file — a banner, license header, or note inserted above it breaks every front-matter-aware parser downstream. If you post-process exports with templates, verify the template preserves the leading block. And when you re-convert a source, overwrite the existing Markdown so the timestamp updates instead of accumulating parallel copies with ambiguous lineage. MarkItDown Online includes the block in every export, and batch ZIP export keeps one Markdown file per source file, so the one-to-one mapping stays intact from upload to archive. Questions: sapsap@qq.com.