Choosing the boundary: local converters, plugins, and Azure backends
MarkItDown offers more than one way to turn a difficult source into Markdown, and the right choice depends on what the workload can trade away. This chapter compares local converters, optional dependencies, third-party plugins, Document Intelligence, and Content Understanding by control, required structure, modality, cost, and ownership. The goal is not to find a universal winner, but to choose the least expansive boundary that can recover the evidence the downstream task actually needs.
Choose the smallest boundary that can recover the needed structure
The local path should be the default when its evidence is sufficient. It keeps the bytes and parsing work in the current process, can operate without a cloud endpoint, and avoids turning every conversion into a billable service call. That matters for sensitive documents, offline workflows, predictable operating costs, and systems whose existing converters already preserve the headings, tables, links, or text needed for analysis. “Local” does not mean risk-free—the process still reads with its own privileges—but it gives the embedding application more direct control over where the bytes go.
The local path is also modular rather than all-inclusive. The core package has a small required dependency set and exposes optional groups for formats such as PDF, Word, PowerPoint, spreadsheets, Outlook messages, audio transcription, and YouTube transcription. This keeps a basic installation lighter and makes the input portfolio visible in deployment configuration. It also creates a condition that is easy to miss: a converter can recognize a file while still being unable to convert it because its optional dependency is absent. MarkItDown reports that condition when the converter is selected, and the dispatcher may try another suitable route, but the fallback is not guaranteed to preserve the same structure.
That is why “install everything” is not automatically the best design. It may broaden the effective format set, but it also increases installation, maintenance, and compatibility surface. A service that accepts only PDF and HTML has different needs from a workstation that processes spreadsheets, legacy email, and media. The useful question is which source structures occur in the real workload and which converter can recover them sufficiently, not how many extras can be enabled in the abstract.
Cloud backends become reasonable when the local representation is materially insufficient and the workload accepts external processing. Document Intelligence is registered when an endpoint is provided and uses Azure's prebuilt-layout analyzer to request Markdown. In the implementation, formulas, high-resolution OCR, and font-style analysis are requested for PDF and image types, while those features are suppressed for Office and HTML types where this integration does not expose them. The service path can therefore be a targeted answer to layout or OCR needs, not a blanket replacement for every built-in converter.
Content Understanding occupies a broader boundary. It detects supported document, image, audio, and video types from extension or MIME information, chooses a modality-appropriate prebuilt analyzer, or uses a custom analyzer when the analyzer's modality is compatible with the input. Its result is passed through to_llm_input(), which can produce Markdown with YAML front matter containing structured fields. That makes it relevant when the task asks not only for readable text but also for domain-specific values such as fields extracted by an analyzer, or when audio and video belong in the same conversion surface.
The two Azure paths should not be described as interchangeable quality switches.