A document conversion pipeline around MarkItDown that preserves provenance and review points
Separate intake, conversion, structural checks and downstream use so a convenient Markdown file does not hide lost meaning.
Define what the converted text will be used for
MarkItDown is a Microsoft Python utility for converting supported documents and other inputs into Markdown for language-model and text-analysis workflows. Its documentation emphasizes useful textual structure rather than high-fidelity page reproduction. Some optional capabilities rely on online services. This guide proposes an intake and review pipeline for public office documents. It contains no conversion benchmark and does not claim that a particular document will be represented perfectly by the tool.
Decide whether the output will support search, summarization, editing or publication. Each purpose requires different checks. Search may benefit from readable paragraphs and reliable source identifiers, while a task involving calculations needs a closer review of tables, units and formulas. A shared extension such as PDF or XLSX does not establish that two files contain equally simple material. Start with the meaning the application needs to preserve, then choose representative inputs.
Register a source before processing it
Give every incoming document a stable identifier and record its origin, retrieval date, version and permitted use. Preserve an original copy or a reliable source location according to the application's policy. Use a separate identifier for each conversion run. This lets a reviewer connect a generated Markdown file to the exact source and settings used, even if a later revision is published under the same filename.
Record expected document characteristics at intake: a spreadsheet with several sheets, a presentation with speaker notes or a PDF containing scanned pages. This simple description helps reviewers notice omissions. It also supports a sensible routing decision when an input falls outside the current pipeline's scope. An unsupported file should receive a clear status and an appropriate review path, rather than being forced through a process whose output is assumed to be complete.
Limit the process to the resources it needs
The official documentation explains that conversion runs with the privileges of the process and recommends appropriately narrow conversion methods for untrusted environments. Review file access and network requirements for the chosen path. A conversion worker for uploaded documents should not inherit broad access merely because the same machine also runs other applications. The specific isolation design must follow the real deployment environment and the current tool documentation.
Keep temporary inputs, outputs and diagnostics organized by run identity. Decide how long each should remain and who may access them. If an optional service receives document content, include that destination in the data-flow record and verify that the material is permitted to be sent there. Avoid putting credentials or unrelated source text into ordinary error logs. These controls support investigation without turning conversion into an uncontrolled document collection service.
Check structure before asking a model to summarize
Use a small set of public fixtures covering headings, lists, links, tables and visual elements important to your application. Compare the converted output with the original. Record missing content, altered relationships and content that requires manual interpretation. A conversion that exits successfully has demonstrated that the process completed; the content review still needs to establish whether the resulting text is suitable for its intended downstream task.
For a spreadsheet fixture, inspect sheet identity, header relationships, units and the meaning of blank values. For a presentation, check whether the explanation needed to understand a slide survived the selected path. For a PDF, inspect reading order and the treatment of footnotes or repeated headers. These are suggested acceptance checks, not a statement that every format exposes the same information through every conversion option.
Keep uncertain material visible
Suppose a public report includes a chart whose labels are necessary to interpret a nearby conclusion. If the conversion omits that relationship, preserve a source reference and flag the passage for review. Do not silently ask a generative model to invent the missing chart values and then store its reconstruction as source text. A clearly marked gap is easier to resolve than a plausible replacement whose uncertain origin has been forgotten.
Keep human corrections distinguishable from the raw converted output. Record what changed, why and where the supporting evidence appears. A corrected working document may be appropriate for later use, but it should not be described as a verbatim extraction. This distinction matters when a summary, citation or dataset is later reused by someone who was not present during the original conversion and does not know which passages involved judgment.
Give downstream stages an explicit readiness signal
The conversion result should carry a status such as ready for the defined task, needs review or unsupported. Choose the actual labels and criteria for the application, and explain their meaning. A downstream summarizer or indexer should be able to distinguish a reviewed document from an unexamined file that merely exists in an output folder. Include the source and run identifiers so errors can be traced back through the pipeline.
A hypothetical summary workflow can require a resolved document identity, readable main text and no outstanding high-impact structural defects before automatic processing continues. Less serious issues may be retained as visible notes. The thresholds should match the consequences of a bad summary. This proposal offers an acceptance structure; it does not establish that these checks are already implemented by MarkItDown or by any particular surrounding application.
Design retries and updates to avoid duplicate evidence
Distinguish a repeated conversion of the same source revision from conversion of a genuinely new revision. Preserve the relationship so that an index does not treat every retry as independent evidence. If a run stops after producing some files, reconcile those outputs with its recorded state before running it again. Give the operator a way to determine whether to reuse, replace or discard partial material according to the application's rules.
When the converter, its dependencies or its options change, reprocess a fixed fixture set first. Compare important relationships rather than only file sizes or line counts. A shorter output could be cleaner or could have lost a section; a larger output could preserve useful content or add irrelevant navigation. Review actual examples and keep the reasoning behind any decision to adopt the new conversion path.
Deliver a package another person can audit
The handover should include the source register, processing configuration, raw output, correction record and readiness decision. Preserve links between them while keeping unnecessary copies under control. Review the tool's current license, any optional service terms and the rights attached to source materials before redistribution. The ability to convert a file does not establish permission to republish its entire contents or illustrations.
A useful pipeline makes it straightforward to answer four questions: where did this text come from, what processing changed it, which checks were completed and what remains uncertain? Those answers help retrieval, summarization and editorial work share a common evidence trail. They also make it easier to repair an error after publication, because the team can identify the affected source revision and downstream products without rebuilding the story from memory.
Primary sources: microsoft/markitdown official repository ↗. Checked on November 13, 2026.
Editorial note: An original COTCC site-team guide, written with AI assistance and checked against primary sources. Scenarios and acceptance criteria are editorial proposals, not reported deployments or benchmark results. Verify current project documentation for features, licensing and costs.
Discussion 0
Oldest firstSign in to join the discussion.
No public comments yet. Start the discussion.