PPTX to Markdown: Don't Ignore Speaker Notes and Slide Show Order

A seemingly clean PPTX-to-Markdown tool can turn each slide's title into an H2, place the body text below it, and output everything in file order. That works fine—until someone hands you a real pitch deck. The slides contain only scattered bullet points, while the actual story, customer quotes, and "why this matters" are buried in the speaker notes. The tool's output looks like a pitch deck but reads like a trailer: all hints, no substance.

Speaker notes are first-class content, not metadata

Treating speaker notes as auxiliary information is a common pitfall in many format converters. The real narrative, context, and customer testimonials often aren't on the projected slide at all—they're in the notes area. The author put their most important expression into the notes when creating the deck, but the converter discards it as noise.

The fix isn't complicated: output notes as a blockquote under the heading, labeled > Notes:, so that downstream RAG pipelines can assign different weights as needed. The document remains a single piece of Markdown, and provenance stays visible.

Behind this change is a more fundamental realization: a converter's job isn't to be faithful to the bytes, but to reconstruct what the author intended to convey. The value of a pitch deck doesn't lie in the slide skeleton—it lies in that layer of information "the reader can't see but the author wrote."

RAG (Retrieval-Augmented Generation) is the current mainstream AI application architecture: split documents into chunks, generate vector embeddings, store them in a vector database, retrieve relevant chunks when a user asks a question, then hand them to a large language model to generate an answer. In this architecture, the converter's output quality directly determines retrieval quality—if notes are discarded, the RAG system will never retrieve the most critical customer testimonials and narrative logic from a pitch deck. This is why the tool chooses to preserve notes as > Notes: blockquotes: downstream pipelines can identify them and assign different weights, for example by chunking notes separately or boosting their priority during retrieval ranking. More generally, "provenance" is the foundation of RAG reliability—only when every piece of text can be traced back to its location and role in the original file (heading, body, notes, figure caption) can the system provide credible citations and judge which layer to trust when information conflicts.

Slide order in XML isn't necessarily the presentation order

Even more surprising is the ordering problem. PowerPoint stores custom slide show order in <p:sldIdLst> within presentation.xml, and decks made by three people separately and then merged often carry a stale custom order that conflicts with the physical slide order. The converter "correctly" reads the file but outputs the wrong presentation flow.

The solution: when the slide ID list exists, parse order by it first; when it doesn't exist, fall back to document order; when the two disagree, log a warning. According to the author's observations, this warning triggers roughly once every 20 PPTs—and those are exactly the PPTs where a human reviewer would also say "wait, this isn't the original flow."

Why presentation order gets overlooked so easily

PPT files aren't produced by a single author on a single timeline. Merging, reuse, and partial updates all leave behind technical debt at the ordering level. Physical order is write order; custom slide show order is the author's final editorial intent. For a converter, the latter represents "how this presentation should be told."

OOXML and presentation.xml: A modern PowerPoint file (.pptx) is essentially a ZIP archive containing numerous XML files that follow OOXML (Office Open XML, ECMA-376 standard). Among them, ppt/presentation.xml is the "master table of contents" for the entire presentation. The <p:sldIdLst> element lists a set of <p:sldId> entries, each with an r:id attribute pointing to a specific slide via the relationship files under ppt/slides/_rels/. This list defines exactly the order the audience actually sees, which can be completely different from the physical numbering order of slide files within the package—similar to how a book's table-of-contents page order can differ from the manuscript binding order. Additionally, PowerPoint supports "Custom Shows," allowing multiple different presentation orders to coexist, and this information is also recorded in extension parts of presentation.xml. Understanding this structure makes it clear why simply iterating slides by filename or physical order goes wrong: filesystem-level sorting and the narrative order the author arranged in XML are two independent systems.

Technical Debt is a concept proposed by Ward Cunningham, originally referring to suboptimal technical decisions made for short-term delivery that generate ongoing "interest" in the future—i.e., additional repair and maintenance costs. In the PPT scenario, this debt manifests as "inconsistency at the ordering level": teams producing chapters separately, copying and pasting from old templates, and temporarily inserting or deleting pages all cause physical write order to diverge from final editorial intent. What's trickier is that this kind of debt is "silent debt"—the file opens normally, presents normally, no errors are thrown, and it only surfaces when you try to parse it structurally with a program. This resembles hidden code smells during refactoring: compiling successfully doesn't mean the design is sound. The author's observation that it triggers "once every 20 PPTs" shows this isn't a high-frequency problem, but because it happens to hit the most important pitch and reporting documents, its destructiveness far exceeds what the frequency suggests. For converter designers, this means you can't just handle the "happy path"—you need to actively detect and report these semantic ambiguities at the parsing layer.

A generalizable conclusion: formats have two layers—an author layer and a reader layer

Extending from PPTX: every format has a layer in the form the author edits and a layer in the form the reader sees, and the two drift over time. Markdown, PDF, Notion pages, Figma files—all have similar two-layer structures. If a converter focuses only on byte-level correctness, it will go wrong at the semantic level.

For slides, respecting notes and presentation order—not just slide order—is the minimum threshold for "understanding this file." This tool is packaged at https://x402.freeq.one/tools/pptx_to_markdown.html, and the author's advice is straightforward: throw a real speech deck into it and see whether the notes show up in the output.

One-line Summary

PPTX-to-Markdown must preserve speaker notes and the true presentation order to reconstruct the author's intent.

Paragraph Summary

This article uses a PPTX-to-Markdown tool as a starting point to point out two common pitfalls in format converters. The first is discarding speaker notes as metadata, when the core narrative, customer testimonials, and "why this matters" in a pitch deck are often hidden in the notes area; the fix is to output notes as a blockquote labeled > Notes:, so downstream RAG pipelines can use them with appropriate weighting. The second is the ordering problem: PowerPoint stores custom slide show order in <p:sldIdLst> within presentation.xml, and merged decks often carry stale order, causing the converter to "read correctly but output the wrong flow." The author recommends parsing by the slide ID list first, falling back to document order, and logging a warning on conflicts (triggered roughly once every 20 decks). The article ultimately generalizes to a broader conclusion: every format has an author editing layer and a reader-visible layer, and a converter's job is to reconstruct author intent, not to be faithful to bytes.