Preserving structure without preserving the page
MarkItDown's converters do not all recover the same kind of evidence. This chapter examines the shared HTML-to-Markdown bridge and then contrasts Office documents, spreadsheets, presentations, and PDFs, so you can predict which relationships are likely to survive and which are only approximations. The practical judgment is simple but important: a clean Markdown result is useful when it preserves the source's reading structure, not because it reproduces the source's visual surface.
HTML provides a common language—but not a neutral one
Several MarkItDown converters use HTML as a staging language before producing Markdown. That is an architectural choice with two benefits. First, HTML already has a vocabulary for headings, paragraphs, lists, links, tables, and images. A Word converter or a presentation-table converter can express the structure it recovered in that vocabulary instead of implementing a second renderer from scratch. Second, one Markdown conversion policy can then be reused across different sources. Headings, links, images, and tables are not formatted by a different set of rules merely because they began in different applications.
The bridge begins by parsing HTML and selecting the document body when one exists. Script and style blocks are removed before the content is rendered. A customized Markdownify layer uses ATX heading markers such as # and ##, turns tables into Markdown table syntax, and keeps the text label of a link with its destination when the destination uses an allowed web or file scheme. Links using JavaScript or other unsupported schemes are reduced to their visible text rather than carried through as active-looking destinations. These are not cosmetic details. They define the boundary between source markup and the textual representation that a downstream model will inspect.
Images expose the same policy. An image can be represented by its alternative text and source, but a source embedded as a long data: URI can overwhelm a document with encoded bytes. MarkItDown truncates such data URIs by default and provides an option to keep them when the caller explicitly needs the embedded data. The default favors a readable and bounded representation; the option acknowledges that a particular application may need more of the original payload. Neither behavior is a claim that the image's visual meaning has been preserved.
The bridge also has a graceful degradation path. Deeply nested HTML can exceed Python's recursion limit while the Markdown converter walks the document tree. In its ordinary mode, MarkItDown warns and falls back to iterative plain-text extraction, preserving usable text even though some markup structure is lost. A strict mode can re-raise the error for callers that would rather fail visibly than accept a degraded representation. The choice makes failure semantics explicit: “conversion returned text” does not necessarily mean “all planned structure was recovered.”
This shared layer is best understood as a policy-bearing interface. It standardizes useful output, but it also removes executable markup, filters some links, shortens some image payloads, and may flatten deeply nested content. Reuse therefore brings consistency and inherited limits at the same time. A converter that emits HTML has gained a common route to Markdown, but it has also accepted the bridge's decisions about what counts as readable structure.
Office files expose semantics; PDFs expose geometry
The contrast among the converters becomes clearer when the source is an Office document. A DOCX file has document-level structures that a library can interpret as paragraphs, styles, headings, and tables. MarkItDown sends the document through Mammoth, which produces HTML, and then sends that HTML through the shared renderer. Caller-supplied and embedded style maps can participate in the conversion, so a style that means “heading” in the document has a chance to become a Markdown heading rather than merely a visually larger line.
The important word is “chance.” The converter preserves styles and tables where the intermediate representation can express them; it does not reproduce the full behavior of a word processor. Page breaks, exact typography, floating placement, and application-specific layout are not the same thing as the document's semantic hierarchy. A heading that remains a heading is valuable to an LLM pipeline, but the Markdown does not promise that the original page would look the same when rendered.
PowerPoint makes the relationship between structure and position more visible. MarkItDown gives each slide a marker, processes shapes in top-to-left reading order, and treats the slide title as a heading. Text areas become text, tables are converted through the HTML bridge, chart data is represented as a Markdown table, and non-empty speaker notes are appended under a notes heading. These decisions turn a canvas of objects into an ordered reading path. They answer a question that raw text cannot answer reliably: which pieces belong to the same slide and in what broad order should a reader encounter them?
Images on a slide show the limits of that projection. The converter can use a generated description when an LLM client and model are available, fall back to embedded alternative text, or use the shape's name. If the image contains information that was not recorded in its text metadata, the Markdown representation may not carry it. Even when a description is present, it is not the same evidence as the original pixels. The slide converter can preserve the location of the image in the sequence and give it a textual label; it cannot promise that the label captures every visual relationship.
Spreadsheets require a different compromise. MarkItDown reads each worksheet as a data frame, emits the sheet name as a heading, and routes the resulting table through HTML-to-Markdown conversion. The result makes the sheet boundary and row-and-column structure visible to a text-analysis system. For a report built from tabular data, that is often more useful than a stream of cell values. It also clarifies what the converter is treating as the primary content: the values arranged in the sheet, not the entire interactive workbook experience.
That choice leaves important questions outside the projection. A spreadsheet's formulas, conditional formatting, merged-cell conventions, hidden visual cues, and interactive behavior may matter to a human analyst even when the extracted table looks complete. The implementation includes a narrow repair for a legacy workbook attribute that can otherwise prevent parsing, which shows that format compatibility sometimes requires targeted recovery. It does not turn the workbook into a lossless model of the spreadsheet application.
Across Word, PowerPoint, and spreadsheets, the pattern is consistent. The converter first recovers an application-level structure, then maps that structure to headings, paragraphs, tables, notes, or links. The result is strongest when the source's meaning is already expressed in those objects. It becomes more approximate when meaning depends on placement, styling, visual grouping, or behavior that the Markdown vocabulary does not contain.
PDFs reverse the problem. A PDF can contain text, but the reading order and table structure may depend heavily on coordinates. Words that appear next to one another on a page may be stored as separate objects, and words stored consecutively may belong to different columns. A converter that merely concatenates extracted strings can produce a plausible sentence while silently crossing a column boundary.
MarkItDown's built-in PDF path therefore uses a heuristic structure-recovery step. It inspects words on each page, groups them by approximate vertical position, and looks for repeated horizontal alignments that resemble columns. It distinguishes long, paragraph-like rows from shorter table-like rows and rejects layouts that look too dense or too much like ordinary prose. When the evidence is sufficient, it emits aligned Markdown tables. When it is not, it keeps ordinary extracted page text instead of forcing every page into a table.
The decision is intentionally conservative. A form may have no visible borders, so border detection alone would miss its structure. But a scientific paper may also use aligned text columns, and treating every alignment as a table would create false structure. The PDF converter's checks are therefore attempts to balance recall and precision: recover tabular relationships when several signals agree, and avoid asserting a table when the page looks more like prose or a complex layout.
If no page is classified as form-like, the converter uses pdfminer's whole-document text extraction, which can provide better spacing for ordinary prose. If pdfplumber fails, it falls back to pdfminer as well. A small post-processing step repairs a recognizable numbering pattern when an extractor has split a partial list number from the sentence that follows it. Pages are closed during the first pass so cached page data does not accumulate unnecessarily. These are all signs of a recovery pipeline with explicit fallback conditions, not a single universal PDF parser.
The built-in PDF converter also has a firm boundary: it does not OCR raster-only pages. A scanned page with no extractable text can therefore remain empty or incomplete on the local path. An OCR-enhanced route can be added separately, but that is a change in the evidence available to the converter, not merely a formatting preference. The distinction matters because text extracted from the PDF's text layer and text inferred from its pixels should not be treated as identical.
The diagram's interfaces explain why these cases belong to one architecture while remaining different systems. The core reader chooses a converter through the common contract. Word, slides, and sheets expose application objects and can reuse the HTML bridge. PDFs expose page geometry and must decide when geometric alignment is strong enough to represent as a table. Each path ends at a Markdown result, but the route to that result determines what a reader may safely infer from it.
What “preserved” should mean in practice
A useful evaluation begins with the source relationship that matters. For a Word report, ask whether headings, paragraphs, and tables remain distinguishable. For a presentation, check whether slide boundaries, title hierarchy, chart values, notes, and broad reading order remain visible. For a spreadsheet, inspect sheet names and column alignment rather than assuming that a table-shaped output contains every workbook behavior. For a PDF, test whether the extracted order and table decisions match the page's intended reading path, especially where columns or borderless forms are involved.
This is more disciplined than asking whether the Markdown “looks right.” Markdown is a reading representation. Its success is measured by whether a later system can use the retained relationships for retrieval, summarization, or analysis. Its failure may be subtle: a heading can become body text, a chart can lose its relation to a title, a table can be flattened, or two columns can be interleaved while every individual word remains present.
The same discipline also prevents overcorrection. A converter does not need to preserve every visual property to be useful for an LLM pipeline. Exact font choice, page margins, animation, and many placement details may be irrelevant to the downstream task. Trying to encode all of them into Markdown could make the result harder to read without restoring the original experience. The goal is not maximum detail in the abstract. It is enough structure for the next system to reason about the source's important content.
At the same time, a clean result should not hide uncertainty. A table produced from spreadsheet rows is grounded in a different source structure from a table inferred from PDF coordinates. A slide note is different from a generated description of an image. Plain-text fallback is different from a successful semantic conversion. MarkItDown's common output contract makes these results composable, but the caller still has to preserve the distinction when the application depends on high-stakes values or exact layout.
The most important conclusion is therefore also the boundary of this chapter: MarkItDown preserves structure selectively. HTML gives several converters a shared route and a consistent output policy. Office formats offer semantic objects that map naturally to Markdown, while PDFs require geometric judgment about reading order and tables. The resulting document can be far more useful than a raw text dump without being a visual clone of the original. Once that distinction is explicit, the next question is how to interpret the Markdown itself: which parts are direct extraction, which are reconstructed, and which require verification before they enter a larger reasoning pipeline.