When text is not enough: archives, media, and model-assisted enrichment
MarkItDown becomes most interesting when the source is not a single text-bearing document. This chapter follows the same normalization contract into archives, EPUBs, web-aware inputs, images, audio, and OCR, where useful content may be nested, spatial, or carried by pixels and speech. The practical judgment is to distinguish composability from certainty: MarkItDown can bring many kinds of content into one Markdown stream, but each boundary it crosses adds its own evidence, dependency, and failure conditions.
An archive is useful only when its members keep their identity
A generic ZIP file is a container, not a document with one obvious reading order. Its members may be unrelated text files, spreadsheets, images, or Office documents. MarkItDown handles that difference by making the ZIP converter a coordinator. It reads a member, gives it metadata based on the member's own filename and extension, sends the member back through convert_stream(), and places the successful result under a heading identifying the member. The outer archive is not allowed to dictate the member's format. A Word document inside a ZIP must reach the Word converter, not be mistaken for another archive because the outer file ended in .zip.
That detail illustrates why recursive conversion is more than a convenience feature. The outer converter owns the composition and the member headings; the ordinary converter registry owns each member's interpretation. Options intended for the conversion, such as output handling for embedded data, can be passed inward, while the archive's own extension and URL are removed so they do not corrupt the member's identity. The result is one Markdown document with a visible boundary between files rather than one undifferentiated stream of their contents.
The behavior also has a deliberate tolerance for partial success. Unsupported members and members whose conversion fails are skipped, while other members remain available in the combined output. That choice favors a useful batch result over an exhaustive account of every failure. It is sensible for a mixed archive in which one obsolete or unfamiliar file should not hide a readable report. It is less suitable when the absence of one member would invalidate the whole analysis. A caller that needs completeness must track archive inventory separately rather than infer it from the Markdown alone.
EPUB shows why a container-aware converter can preserve more meaning than generic unpacking. An EPUB is packaged as a ZIP, but its content is organized through a container file, an OPF package document, a manifest, and a spine. MarkItDown follows the spine order, extracts book metadata, and sends the selected HTML or XHTML content through the shared HTML converter. The spine supplies a semantic reading sequence that a generic ZIP member listing cannot provide. The difference is not the ability to open compressed files; it is the ability to understand the container's own organizing relationship.
The same boundary supports specialized sources that are not all containers. An Outlook message is read as an email with headers and body rather than as arbitrary binary data. A Jupyter notebook separates Markdown cells from code and raw cells. CSV is parsed into rows, padded to a consistent width, and escaped so that a pipe inside a value does not become a false column boundary. RSS and Atom content is interpreted as feeds with entries, links, and markup. A YouTube URL can contribute page metadata and a transcript, then fall back to ordinary HTML when no video-specific content is extracted.