Markdown vs DOCX vs site pages: choosing a knowledge format for RAG on SharePoint

You're building (or feeding) an AI assistant that answers questions from organizational knowledge stored in SharePoint — a query-time RAG pipeline over SharePoint Search, a Copilot-adjacent tool, or your own agent. The question this guide answers: in what format should that knowledge live?

The candidates people actually consider: site pages (modern .aspx), Word documents (.docx), Markdown files (.md), and — often by accident — list items with rich-text columns.

TL;DR decision table

For the machine half of the pipeline, Markdown wins outright: it reads best by a wide margin (extraction quality, token efficiency) and — despite what the official parsed-file-types table implies — SharePoint Online full-text indexes it, so discovery works too. The real trade-off left on the table is authoring UX: pages and Word are where humans write comfortably, Markdown isn't (yet) first-class to edit in M365.

Where the format matters

However a pipeline is built, knowledge reaches the model in two moves: something has to find it — usually the search index, trimmed to what the user may see — and something has to read it into a limited budget of characters or tokens. The four formats behave very differently in both.

Format by format

Site pages — great discovery, terrible extraction

Pages are parsed by the HTML format handler, so their content is fully searchable — best-in-class discovery. But when the pipeline deep-reads a page, the cheap approach (fetch the page URL) returns the fully rendered page: suite chrome, scripts, embedded JSON state — often 100+ KB wrapping a few KB of actual content. Pipelines then strip tags with a regex and hope; if the fetch is truncated to fit a budget, the real content can fall behind the cutoff entirely.

The authored content actually lives in the CanvasContent1 field of the SitePages item — much closer to the source, but it's web-part JSON mixed with HTML fragments, so extracting it cleanly is nontrivial too (see creating modern pages via REST for what that field looks like). If your pipeline reads pages, read CanvasContent1 and strip that, rather than fetching the rendered page.

DOCX — good discovery, lossy extraction

Fully indexed, so discovery is fine. Extraction requires a real parser (mammoth in the browser, or a server-side library), which costs a download of the whole binary (documents are commonly megabytes for pages of text) plus parse time — and typical raw-text extraction flattens the structure: headings, lists and tables melt into undifferentiated paragraphs. The LLM still gets the words, but loses the outline that makes a knowledge article skimmable, and tables often become word soup.

Where DOCX shines is authoring: everyone has Word, tracked changes, comments, co-authoring.

Markdown — the machine-native format

For the reading half, Markdown is close to ideal:

• The file is the text — fetch + read, no parser, no server round-trip.
• Structure survives in-band: # headings, lists, tables, code fences cost single characters instead of kilobytes of markup, and LLMs are heavily trained on Markdown — they follow its structure natively.
• Practically the whole character/token budget carries signal instead of scaffolding.

And the discovery half works too — with an asterisk worth knowing about. The official parsed-file-types table doesn't list .md, which reads as "bodies never reach the index". A live probe says otherwise: SharePoint Online full-text indexes .md bodies (verified via /_api/search/query with the hit highlight coming from the body — full story). If this is load-bearing for your design, spend the two minutes re-running that probe on your tenant; the docs and the service clearly move at different speeds.

Metadata still pays off — not as a workaround, but as quality: rich Title/description/keyword columns lift ranking and give a reader a cheap high-signal snippet without re-reading the file.

Markdown's real weakness in M365 is authoring: there's no first-class browser editor, so either your authors are comfortable in VS Code/Typora-land, or an app generates the files (see below).

List items — fine for apps, invisible to document pipelines

Rich-text stored in multiline columns is indexed for search in general, but document-oriented RAG pipelines commonly filter to IsDocument:1 — and then list-based knowledge never even enters the candidate set. The content is also typically wrapped in app-specific HTML and reachable only through the app's UI.

If your knowledge base is an app backed by lists (a common and perfectly good design for the human experience), treat AI as a second consumer: publish a file derivative of each approved article into a document library.

Token economics — with the numbers

Deep-read budgets are finite (thousands of characters per source, not millions), and every character of wrapper markup displaces a character of content. The measured version: the same ~500-word article costs 573 tokens as Markdown, ~541 as clean-extracted DOCX, 612 as extracted PDF (page furniture, re-tokenized per page) — but 3,213 tokens if you dump the raw document.xml, and 1,236 if you feed a page's CanvasContent1 field verbatim instead of stripping it. Same budget, wildly different amounts of usable knowledge — and retrieval quality follows.

The lesson isn't "pick a format", it's "extract cleanly, whatever the format". Full method, per-format breakdown, a Czech-vs-English language tax, and a reproducible harness: What each format costs the model.

The practical upshot

Author where the UX is; give the machine clean text. Keep writing in whatever has the best human workflow — Word, the page editor, an app with forms and approval — and wherever a machine reads the knowledge, make a clean text rendition available next to the original (Markdown is the natural choice), regenerated whenever the source changes. Good titles and descriptions help discovery whichever format you pick.

Related

• Don't trust the parsed-file-types table: SPO does index .md
• Create a modern page via REST — CanvasContent1 is JSON
• Search queries that actually work