Markdown vs HTML for LLM Context: What Actually Wins

Executive Summary

There is a quiet decision hiding inside every retrieval and agent pipeline, and most teams make it by accident: what format do you hand the model? Raw HTML scraped straight off the page? Cleaned Markdown? Something in between?

It sounds like a plumbing detail. It is not. The format you feed a large language model changes token cost, retrieval accuracy, structural fidelity, and how easily the model can reason over the content. Get it wrong and you pay for thousands of useless <div class="wrapper"> tokens, confuse the model with layout noise, and watch your answer quality quietly sag.

This guide settles the Markdown-vs-HTML question the honest way: it depends on the stage and the goal — but for most LLM context, clean Markdown wins, and here is exactly when it does not.

You will learn how each format behaves under tokenization, how it affects chunking and retrieval, where HTML's extra structure genuinely helps, and how to build a format strategy that is measurable rather than superstitious.

1. Problem Statement

Teams building on LLMs usually think about models, prompts, and vector databases. They rarely think about the shape of the text they pour into all three. That omission causes a predictable set of failures.

1. You pay for markup you don't need. A single blog paragraph wrapped in production HTML can carry ten times its own weight in <div>, class, style, and data-* attributes. Every one of those characters becomes tokens, and tokens are money, latency, and context-window pressure. Feed raw HTML and you are literally paying the model to read CSS class names.
2. Layout noise drowns meaning. HTML describes presentation: grids, wrappers, tracking pixels, SVG icons, cookie banners. The model has to work harder to separate "the actual article" from "the scaffolding around it." More noise means lower signal, and lower signal means weaker retrieval and vaguer answers.
3. Naive Markdown loses structure the model needed. The opposite mistake is just as real. Strip a page down too aggressively and you flatten a pricing table into a run-on sentence, drop the heading that told you which section you were in, or lose the link that made a claim verifiable. Now the format is clean but lossy.
4. Inconsistent formatting breaks everything downstream. If some documents arrive as HTML, some as Markdown, and some as plain text, your chunker and embedder see three different worlds. Retrieval quality becomes a function of which source a fact came from — an untraceable, maddening bug.
5. The choice is never audited. Most pipelines pick a format once, in week one, based on whatever the scraping library returned by default. Nobody measures whether the other format would retrieve better or cost less. The decision is superstition, not evidence.

The 2026 lens. The same principle that wins in search wins here: information gain per token. The best format is the one that preserves the maximum meaning in the minimum, cleanest representation — and lets you prove it. This guide treats format as a first-class, measurable engineering choice, not a default you inherit.

2. Definitions: Markdown, HTML, and "AI Context"

Before comparing, define the three terms precisely, because most arguments online are people talking past each other.

HTML (HyperText Markup Language) is a presentation-and-structure language for browsers. It uses angle-bracket tags (<h1>, <table>, <div>, <span>) and attributes (class, id, style, data-*) to describe how content is organized and how it should be rendered. Crucially, most HTML on a real web page is not content — it is scaffolding: layout containers, styling hooks, scripts, analytics, and accessibility plumbing.

Markdown is a lightweight, human-readable text format that encodes structure with minimal syntax: # for headings, - for lists, | for tables, backticks for code, [text](url) for links. It captures the semantics that matter for reading — hierarchy, emphasis, lists, tables, code, links — while discarding presentation. A Markdown document is close to how a person would type the content in a plain notepad, plus a few structural marks.

"AI Context" is the text you place inside the model's context window at inference time — the retrieved chunks in a RAG system, the fetched page in an agent, or the examples in a prompt. Better AI context means text that is:

• Faithful — it preserves the facts, structure, and relationships of the source.
• Efficient — it spends few tokens on anything that isn't meaning.
• Consistent — every document arrives in the same predictable shape.
• Traceable — you can map any claim back to its source location.

The whole Markdown-vs-HTML debate is really a debate about which format maximizes faithful, efficient, consistent, traceable context.

3. Why Format Even Matters to an LLM

If a model is "smart," why does formatting change its output at all? Three mechanical reasons.

Tokenization: every character has a price. LLMs don't read characters or words — they read tokens, sub-word units produced by a tokenizer. HTML markup tokenizes badly: <div class="col-md-6 wrapper"> fragments into many tokens that carry zero information about the actual content. Markdown's syntax (#, -, |) is far leaner. On a typical article, the same content can cost 2–5× more tokens as raw HTML than as clean Markdown. That difference is pure overhead — you pay it on every request, and it eats into the finite context window.

Attention: signal-to-noise drives quality. Transformer attention has to distribute focus across everything in the window. When 60% of the tokens are layout scaffolding, the model spends attention "budget" parsing structure that doesn't matter, and the genuinely important sentences compete with </span></div></div> for prominence. Cleaner input means a higher ratio of meaningful tokens, which correlates with more accurate, less distractible responses.

Structure: models learned from Markdown-shaped text. Modern LLMs were trained on enormous amounts of Markdown (READMEs, forums, docs, chat) and understand its conventions natively. A # heading, a |-delimited table, or a fenced code block is unambiguous to the model. HTML is understood too, but it arrives tangled with presentational noise the model must first see past. Giving the model the structure it already reasons in fluently reduces the work required to extract meaning.

The core insight: the model doesn't care how the page looked in a browser. It cares about the semantic structure and the facts. HTML encodes both meaning and presentation; Markdown encodes mostly meaning. For AI context, the presentation half is dead weight — sometimes harmless, often harmful, always paid for.

4. Architecture: Where Format Lives in the Pipeline

Format isn't a single choice — it's a transformation that happens at a specific place in your ingestion pipeline, and where you make it determines what you can preserve.

The critical stage is Convert, and it sits right after extraction:

Fetch (raw HTML) → Extract (main content) → Convert (format decision)
    → Clean → Chunk → Embed → Index → Retrieve → Context → LLM

The critical stage is Convert, and it sits right after extraction:

1. Fetch returns raw HTML (or a rendered DOM). This is the richest but noisiest representation.
2. Extract identifies the main content and its structure — headings, tables, lists, code, links — discarding chrome.
3. Convert is the fork in the road: serialize that extracted structure as Markdown, keep a cleaned-HTML subset, or emit structured JSON. This is the Markdown-vs-HTML decision point.
4. Everything downstream — cleaning, chunking, embedding, retrieval, and the final context — inherits the consequences of that choice.

Why the placement matters: if you convert to Markdown before extracting structure, you can lose tables and headings irreversibly. If you convert after a structure-aware extraction, Markdown keeps the meaning and drops only the noise. Extract structure first, then choose the leanest format that preserves it.

Key principle: format is a projection, not a source of truth. Keep the raw HTML in cheap storage so you can re-project into any format later. Your context format (usually Markdown) is a derived, replaceable view — never the only copy of the data.

5. Pillar/Cluster Strategy for This Topic

This article is a pillar page on content formatting for AI. It answers the headline question in depth and links out to focused cluster articles that each drill into one sub-decision.

Recommended cluster articles (each links back to this pillar):

1. HTML-to-Markdown conversion: patterns that don't lose tables
   The practical "how-to" behind the format decision. It covers conversion techniques that survive real-world pages — mapping <h1>–<h6> to # levels, <pre><code> to fenced blocks, and especially how to handle tables (merged cells, multi-level headers) without flattening them into unusable prose. Why it matters: naive converters silently destroy the highest-value content (tables, code), so this article shows the patterns that keep meaning intact.
2. Token counting and cost modeling for RAG context
   Turns the "Markdown is cheaper" claim into actual numbers. It shows how to count tokens with a real tokenizer, compare HTML vs Markdown on your own corpus, and model the recurring cost of format overhead (tokens × chunks × queries × price). Why it matters: proves the efficiency argument with math instead of assumptions, and helps justify format choices to stakeholders.
3. Structure-aware chunking for Markdown documents
   How the format you chose feeds the next stage. It explains splitting on heading boundaries, keeping tables and code blocks whole, sizing chunks to the embedding model, and attaching heading-path metadata. Why it matters: clean Markdown makes semantic chunking easy; this article shows how to exploit that for better retrieval.
4. Preserving links and citations through format conversion
   Focuses on traceability. It covers keeping [anchor text](url) intact during conversion, capturing source URLs and section anchors as metadata, and mapping every chunk back to its origin. Why it matters: links are how you verify claims and debug wrong answers — lose them in conversion and you lose auditability.
5. When to keep HTML: tables, forms, and semantic attributes
   The honest counter-argument. It documents the specific cases where Markdown is lossy and a minimal HTML subset wins — complex tables, <time datetime>, microdata, forms, ARIA semantics. Why it matters: balances the guide so it's credible, not dogmatic, and gives readers a clear "exception list."
6. JSON and XML as LLM context: structured alternatives
   Widens the debate beyond two options. It compares JSON/XML for cases where content is inherently structured (API data, catalogs, records) and shows when a schema beats free-form Markdown. Why it matters: for structured/tabular data, a typed format often produces cleaner, more reliable context than either Markdown or HTML.
7. Prompt injection through markup: sanitizing scraped content
   The security angle. It shows how hidden HTML (comments, display:none text, attributes) can smuggle malicious instructions into a model, and how conversion + sanitization neutralizes them. Why it matters: scraped content is untrusted input; stripping to clean Markdown is itself a defense, and this article explains how to do it safely.

Internal linking rule: the pillar links down to each cluster with descriptive anchor text, and every cluster links up to this page and sideways to one or two siblings. This builds a tight topical graph around "content formatting for LLMs" that signals genuine subject authority.

6. Search Intent and Content Coverage

The query "Markdown vs HTML for LLMs" is fundamentally a decision-and-comparison intent: the reader wants a clear recommendation plus the reasoning to defend it.

Primary intent: "Which format should I feed my LLM, and why?"

Secondary intents this guide deliberately covers:

• "Which is cheaper / uses fewer tokens?" → Token Efficiency (§9) and Cost Engineering (§14).
• "Which preserves my tables and code correctly?" → Complex Content (§11).
• "Does format affect retrieval accuracy?" → Chunking and Retrieval Impact (§12).
• "When is HTML actually the right call?" → HTML Deep Dive (§8) and Decision Framework (§17).
• "How do I convert cleanly?" → Configuration Patterns (§16).

Coverage principle: a thin article just declares "Markdown is better." A page that ranks and helps proves it with token math, retrieval reasoning, and an honest list of exceptions. Information gain here comes from the nuance — the when-not-to is what competitors omit.

7. Markdown Deep Dive: Strengths and Weaknesses

Markdown is the default recommendation for LLM context for good, concrete reasons — but it is not free of trade-offs.

Strengths

• Token efficiency. Minimal syntax means the vast majority of tokens are content, not markup. This is the single biggest win and it compounds on every request.
• Native model fluency. LLMs read and write Markdown constantly during training. Headings, lists, tables, and fenced code are unambiguous to them.
• Human-auditable. You can open a Markdown chunk and instantly see what the model sees. Debugging retrieval becomes a reading exercise, not a DOM-inspection chore.
• Clean structure signals. # heading levels give the model (and your chunker) a reliable outline of the document's hierarchy.
• Portable and diff-friendly. Plain text stores, versions, and diffs cheaply — ideal for change detection and reproducibility.

Weaknesses

• Limited expressiveness. Standard Markdown has no native concept of colspans, nested tables, cell alignment beyond basics, or rich metadata. Complex tables degrade.
• Ambiguity at the edges. Multiple Markdown "flavors" (CommonMark, GFM) differ on tables, footnotes, and task lists. Inconsistent generation causes inconsistent parsing.
• Lossy for semantics HTML encodes explicitly. ARIA roles, <time datetime>, microdata, and <abbr> meanings can vanish in conversion unless you capture them as metadata first.
• Whitespace fragility. Nested lists and code fences are sensitive to indentation; sloppy conversion produces broken structure.

Verdict on Markdown: it is the best general-purpose context format because it maximizes meaning-per-token and matches how models think. Its weaknesses are real but mostly appear at the extremes — dense tables and semantic metadata — which you handle by capturing those as structured fields alongside the Markdown, not by abandoning it.

8. HTML Deep Dive: Strengths and Weaknesses

HTML is usually the wrong format to hand a model directly — but "usually" is not "always," and understanding its strengths tells you exactly when to keep it.

Strengths

• Maximum structural expressiveness. Complex tables (colspan/rowspan), nested structures, forms, and definition lists have precise, standardized representations. Nothing about the layout is ambiguous.
• Explicit semantics. Tags like <time datetime="2026-01-01">, <article>, <nav>, <abbr title="...">, and microdata/JSON-LD carry machine-readable meaning that Markdown simply cannot express.
• Attribute-level metadata. data-* attributes, ids, and classes can carry IDs, timestamps, or source anchors useful for traceability — if you deliberately keep the right ones.
• Lossless intermediate. Because raw HTML is the source, it is by definition the most faithful representation you can hold before any transformation.

Weaknesses

• Token bloat. The dominant problem. Real-world HTML is mostly non-content markup; feeding it directly wastes tokens, money, and context window.
• Noise and distraction. Scripts, styles, tracking, wrappers, and chrome dilute the signal the model needs, degrading attention and retrieval.
• Injection surface. Hidden elements, comments, and attributes are a natural carrier for prompt-injection payloads (see §15).
• Inconsistency across templates. Two sites express the same table with wildly different DOMs, so "feed the HTML" yields inconsistent input.

Verdict on HTML: keep it as your stored source of truth and reach for a cleaned, minimal HTML subset as context only when the content's meaning genuinely depends on structure Markdown can't express — primarily complex tables and explicit semantic attributes. Raw production HTML should almost never enter a context window unfiltered.

9. Head-to-Head: Token Efficiency

This is where Markdown wins most decisively, and it's worth making the mechanism concrete.

Consider a simple two-row pricing table. In production HTML it might look like:

<div class="pricing-wrapper">
  <table class="tbl tbl--striped" data-testid="pricing">
    <thead><tr><th class="c1">Plan</th><th class="c2">Price</th></tr></thead>
    <tbody>
      <tr><td class="c1">Basic</td><td class="c2">$10</td></tr>
      <tr><td class="c1">Pro</td><td class="c2">$30</td></tr>
    </tbody>
  </table>
</div>

The same information in Markdown:

| Plan  | Price |
|-------|-------|
| Basic | $10   |
| Pro   | $30   |

The Markdown version conveys identical facts in a fraction of the characters — and those characters tokenize efficiently, while the HTML fragments class="c1", data-testid, and the wrapper div into many meaningless tokens.

Why this matters at scale:

• Cost. If you retrieve 8 chunks per query and each carries 3× token overhead as HTML, you pay roughly 3× for input tokens on every single request, forever.
• Context window. A finite window fills with markup instead of meaning, so you fit fewer real facts — directly lowering answer quality on complex questions.
• Latency. More input tokens means slower time-to-first-token. Format overhead is a permanent tax on responsiveness.

Rule of thumb: for prose-heavy web content, expect Markdown to use somewhere between one-half and one-fifth the tokens of the equivalent raw HTML. Measure it on your corpus with a real tokenizer — don't trust a blog's single number, including this one.

10. Head-to-Head: Structural Fidelity

Token efficiency is meaningless if the lean format drops facts. So the real question is: does Markdown preserve enough structure? For the overwhelming majority of web content, yes — with specific exceptions.

What Markdown preserves faithfully:

• Heading hierarchy — the document outline the model uses for context.
• Ordered and unordered lists, including reasonable nesting.
• Emphasis, inline code, blockquotes.
• Links with anchor text — critical for traceability and claim verification.
• Simple-to-moderate tables and fenced code blocks with language hints.

Where HTML retains an edge:

• Complex tables with merged cells, multi-level headers, or spanning rows.
• Explicit machine semantics — datetime, microdata, ARIA roles, unit annotations.
• Deeply nested or non-linear structures (e.g., interactive widgets, forms).

The practical resolution is not "pick the lossless format" — it's extract structure first, serialize to Markdown, and capture the few HTML-only semantics as explicit metadata fields. A published date becomes a published: field in the chunk's metadata, not a lost <time> tag. A complex table becomes either faithful Markdown or, when that fails, a small structured block. You get Markdown's efficiency and HTML's meaning, because you separated the two instead of choosing between them.

Fidelity test: convert a representative sample to Markdown, then ask a knowledgeable reviewer, "Is any fact or relationship missing versus the rendered page?" If the answer is "only the merged-cell table on page 12," you've found your exception — handle that page specially, not your whole corpus.

11. Head-to-Head: Tables, Code, and Complex Content

Complex content is where the debate actually gets interesting, because this is where naive Markdown conversion visibly fails.

Tables. Simple grids convert perfectly to Markdown and read cleanly for the model. Problems appear with:

• Merged cells (colspan/rowspan). Markdown has no native representation. Options: flatten with repeated values, linearize into "key: value" sentences per row, or retain a minimal HTML <table> for that table only.
• Multi-level headers. Collapse into compound column names ("Q1 Revenue") during conversion so each cell stays self-describing.
• Very wide tables. Consider linearizing to record form so a retrieved chunk keeps each row self-contained rather than truncating columns.

Code. Markdown wins clearly here. Fenced code blocks with language hints are unambiguous, preserve whitespace, and match training data exactly. HTML's <pre><code> with syntax-highlighting <span>s is the worst case — it shatters every keyword into span-wrapped tokens. Always convert code to fenced Markdown blocks and strip highlight markup.

Other complex content.

• Math: preserve LaTeX/MathML as delimited expressions; don't let conversion mangle it.
• Lists with embedded structure: Markdown handles nesting well if indentation is generated carefully.
• Images/figures: keep alt text and captions as Markdown — they carry meaning; drop the binary and layout wrappers.

The complex-content rule: default to Markdown, detect the specific structures it can't express (mainly merged-cell tables and explicit semantics), and handle only those with a targeted fallback — minimal HTML or a structured block. Never downgrade your entire corpus to HTML because 2% of tables are hard.

12. Head-to-Head: Chunking and Retrieval Impact

Format doesn't just affect the final context handed to the model — it shapes every step in between, and chunking is where the effect is largest.

Format drives chunk boundaries Good chunking splits on semantic boundaries — sections, headings, coherent ideas. Markdown makes those boundaries explicit and machine-readable: a ## heading is an unmistakable split point, and the heading text itself becomes clean metadata ("this chunk is under Pricing → Enterprise"). Raw HTML buries the same boundary inside <h2 class="..."> wrapped in layout <div>s, so a naive character-splitter cuts mid-tag and produces chunks that begin with </div></section><div class=. That is not a chunk — it's shrapnel.

Format affects embedding quality Embeddings encode meaning. When markup noise inflates a chunk, the embedding is partly "about" class names and div structure rather than the actual topic. Two chunks with identical content but different wrapper markup can even embed to slightly different vectors — hurting the consistency retrieval depends on. Clean Markdown produces embeddings dominated by content, which is exactly what you want the vector to represent.

Format affects what fits Because HTML is token-heavy, a fixed-size chunk holds less actual content as HTML than as Markdown. Your retrieval unit becomes diluted: the same 512-token chunk might carry two paragraphs of meaning in Markdown but only one — plus scaffolding — in HTML. Fewer facts per chunk means you need more chunks to answer, which crowds the context window and raises cost.

Retrieval takeaway: Markdown improves chunking (clear boundaries), embedding (content-dominated vectors), and density (more meaning per chunk) simultaneously. This is why format choice quietly moves your recall@k — and why you should A/B test formats against a real evaluation set rather than assuming.

13. Grounding, Citations, and Traceability by Format

Grounded answers require mapping every claim back to a source. Format affects how easily you preserve that trail.

Links are the currency of traceability Both formats can preserve links, but they behave differently. Markdown's [anchor text](url) keeps the human-readable anchor and the target together, compactly — the model sees both the claim and where it came from. HTML preserves links too, but wrapped in attributes and often decorated with tracking parameters and rel noise that add tokens without adding meaning. When you convert to Markdown, you get a natural moment to normalize links: strip tracking params, resolve relatives to absolutes, and keep anchor text intact.

Metadata is where HTML semantics survive The traceability signals HTML encodes — <time datetime>, canonical URLs, author microdata — shouldn't be discarded just because your context format is Markdown. Capture them during extraction into a structured metadata object attached to each chunk: source_url, heading_path, published, modified, content_hash. This is the best of both: Markdown for the content the model reads, structured fields for the provenance your system audits.

Citation-ready chunks Because Markdown chunks carry a clean heading path, a retrieved chunk can be cited as "Source page → Section → Subsection" without parsing a DOM. Even if you never show citations to users, this makes debugging a wrong answer a two-minute trace instead of an archaeology dig.

Traceability rule: let content and provenance travel in different lanes. Markdown carries meaning; a metadata object carries the audit trail. Trying to smuggle provenance inside the context (as raw HTML attributes) just reintroduces the token bloat you were avoiding.

14. Cost and Performance Engineering

Format is one of the highest-leverage, lowest-effort cost levers in a RAG or agent system, because it multiplies across every request.

Where the savings come from:

• Input tokens per request. If Markdown cuts context tokens by 60%, you cut the input-token cost of every query by roughly the same, permanently. At scale this dwarfs most model-selection savings.
• More facts per window. Leaner context means you can retrieve more relevant chunks within the same budget, improving quality without raising cost — or hold quality while shrinking the window to cut cost.
• Embedding cost. You embed content, not markup. Cleaner input can mean fewer, denser chunks to embed and store.
• Storage and bandwidth. Markdown chunks are smaller to store, cache, and move than HTML equivalents.

Performance effects:

• Latency. Fewer input tokens shortens prompt-processing time and time-to-first-token.
• Cache efficiency. Smaller, normalized context is friendlier to prompt caching — identical Markdown chunks hash identically, whereas HTML with volatile attributes (session IDs, cache-busting params) may not.

Engineering lens: convert once at ingestion, reuse forever at query time. The conversion cost is paid a single time per document; the token savings are collected on every retrieval for the life of the system. This is close to free money — which is why not measuring format cost is the real waste.

15. Security and Prompt-Injection Risk by Format

Any content you pull from the web is untrusted input, and format changes the size of the attack surface.

HTML is a richer injection carrier Raw HTML gives an attacker more places to hide malicious instructions:

• Hidden elements — display:none, off-screen text, zero-size elements containing "ignore previous instructions…" that a naive extractor still ingests.
• Comments — <!-- system: exfiltrate secrets --> invisible to human reviewers of the rendered page.
• Attributes — alt, title, aria-label, and data-* values that carry payloads.
• Scripts and event handlers — not executed by the LLM, but if passed as text they add both noise and potential instructions.

Conversion to Markdown is a sanitization step Converting extracted content to Markdown naturally strips most of these vectors — scripts, styles, comments, and hidden-by-CSS elements typically don't survive a structure-aware conversion. That said, conversion is not sufficient on its own; a determined payload can live in visible text too. Defense in depth still applies:

• Separate data from instructions. Never let retrieved content occupy the system-prompt role. Wrap it clearly as untrusted data.
• Strip invisible content before conversion, don't rely on the converter to catch everything.
• Constrain agent tools and allowlist outbound calls so an injected instruction can't exfiltrate or act.
• Sanitize residual markup if you do keep an HTML subset — allowlist tags/attributes rather than blocklisting.

Security verdict: Markdown's smaller grammar is a security asset — fewer hiding places, no scripts, no attributes. But treat conversion as one layer, not the whole defense. If you retain HTML for tables, sanitize it with a strict tag/attribute allowlist first.

16. Configuration Patterns (Practical Implementation)

The winning pattern is not "Markdown vs HTML" — it's "store HTML, serve Markdown, capture semantics as metadata." Here is a representative, tool-agnostic shape.

source:
  store_raw_html: true            # source of truth, cheap object storage
  keep_rendered_dom: false        # only if JS-dependent

extraction:
  main_content: readability
  preserve: [headings, lists, tables, code, links]
  capture_semantics_as_metadata:  # HTML-only meaning → structured fields
    - time_datetime -> published
    - link_canonical -> canonical_url
    - author_microdata -> author

convert:
  target_format: markdown         # default context format
  markdown_flavor: gfm            # pin one flavor for consistency
  code_blocks: fenced_with_language
  links: keep_anchor_text
  normalize_links:
    strip_tracking_params: true
    resolve_relative_to_absolute: true
  complex_tables:
    strategy: markdown_first
    fallback: minimal_sanitized_html   # only for merged-cell tables

sanitize:
  remove: [scripts, styles, comments, hidden_elements]
  html_fallback_allowlist:
    tags: [table, thead, tbody, tr, th, td]
    attributes: [colspan, rowspan]

chunk:
  strategy: semantic              # split on Markdown headings first
  attach_metadata: [source_url, heading_path, published, content_hash]

evaluate:
  compare_formats: true           # A/B markdown vs html-subset
  metrics: [tokens_per_chunk, recall_at_k, groundedness, cost_per_query]

Why this shape works: it refuses the false binary. Raw HTML stays as the replayable source of truth; Markdown is the lean, model-friendly projection used as context; the handful of HTML-only semantics are rescued into metadata; and complex tables get a targeted, sanitized fallback — all while an evaluation block proves the choice on your own data.

17. Decision Framework: When to Use Which

Use this as your default policy, then override per-source only with evidence.

• General web/article content for RAG — Recommended format: Markdown — Why: Best meaning-per-token; native model fluency
• Code, docs, technical content — Recommended format: Markdown — Why: Fenced blocks preserve code perfectly
• Simple/moderate tables — Recommended format: Markdown — Why: Converts faithfully, stays lean
• Merged-cell / multi-header tables — Recommended format: Minimal sanitized HTML (that table only) — Why: Markdown can't express spans
• Content needing explicit semantics (dates, microdata) — Recommended format: Markdown + metadata fields — Why: Rescue semantics without HTML bloat
• Agent fetching a page mid-task — Recommended format: Markdown — Why: Lean context, lower injection surface
• Source of truth / archival storage — Recommended format: Raw HTML — Why: Lossless, replayable into any format
• Fine-tuning dataset from web — Recommended format: Markdown — Why: Clean, consistent, matches model priors
• Structured records (products, specs) — Recommended format: JSON (see §20) — Why: Key–value data isn't prose at all

The one-line policy: Store HTML, serve Markdown, rescue HTML-only semantics into metadata, and fall back to a sanitized HTML subset only for tables Markdown genuinely cannot express — and prove every exception with an eval.

When in doubt, default to Markdown. The burden of proof is on HTML: it must demonstrate that the specific content carries meaning Markdown loses. For the long tail of ordinary web pages, it can't — so Markdown wins by default.

18. Troubleshooting: A Format Decision Tree

When a RAG or agent pipeline gives bad answers, format is an underrated suspect. Walk this tree before blaming the model.

Symptom: "The model ignores or misreads retrieved context."

• Inspect a raw chunk. Is it full of <div class=…>, </span>, or comment tags? → You're feeding HTML shrapnel. Fix: convert to Markdown at ingestion.
• Are chunks starting/ending mid-tag? → Your splitter is cutting through markup. Fix: split on Markdown headings, not raw characters.

Symptom: "Costs are higher than expected for the answer quality."

• Measure tokens_per_chunk. Is markup a large fraction? → HTML bloat. Fix: Markdown conversion typically recovers 40–70% of context tokens.
• Are you retrieving many chunks to answer simple questions? → Low density per chunk. Fix: leaner format packs more meaning per retrieval unit.

Symptom: "Tables come back garbled or with wrong numbers."

• Simple table mangled after conversion? → Converter misconfigured. Fix: enable GFM tables; verify header/row alignment.
• Merged/multi-header table flattened incorrectly? → Markdown genuinely can't express it. Fix: fall back to a sanitized HTML subset for that table only.

Symptom: "Answers cite the wrong section / can't be traced."

• Chunks lack heading context? → Metadata not captured at chunk time. Fix: attach heading_path + source_url during chunking.
• Dates/authors missing? → Semantics lost in conversion. Fix: capture <time datetime>, canonical, microdata into metadata fields.

Symptom: "Suspicious model behavior after ingesting a page."

• Hidden text or comments in the source? → Possible prompt injection. Fix: strip hidden/comment/script content before conversion; isolate retrieved data from the instruction role.

Rule of thumb: if the answer is wrong, look at the actual bytes in the chunk before touching prompts or swapping models. Most "model problems" are really "context problems," and format is the first place they show up.

19. Enterprise and Cloud Considerations

At team and org scale, format decisions become governance decisions.

Standardize the projection, not just the storage. Pick one Markdown flavor (e.g., GFM), pin it, and document it. When five teams each convert HTML differently, you get five inconsistent chunk styles feeding one shared index — and inconsistent embeddings. A single, versioned conversion contract keeps retrieval behavior stable across teams.

Keep raw HTML as the system of record. Store the original HTML in cheap object storage (S3/GCS/Azure Blob) as the replayable source of truth. When you improve your extraction or change Markdown flavor, you re-project from source rather than re-scraping the web. This makes format changes a batch job, not a crawl.

Version everything that touches meaning. Extraction rules, converter version, sanitization allowlist, and chunker config should all be versioned and stamped onto chunks (e.g., a pipeline_version field). When answer quality shifts, you can tie it to a specific config change and roll back.

Cloud cost shape.

• Storage: raw HTML (cold) + Markdown chunks (warm) + vectors (hot). Tier accordingly.
• Compute: conversion is a one-time ingestion cost; the token savings recur on every query — so the ROI compounds with query volume.
• Caching: normalized Markdown hashes stably, improving prompt-cache hit rates across a fleet.

Governance and compliance. Because provenance lives in structured metadata (source_url, published, content_hash), you get auditability "for free": you can prove what a chunk was, where it came from, and whether it changed — which is exactly what security and legal reviews ask for.

20. Alternatives and Comparisons: JSON, XML, and Hybrid

Markdown vs HTML isn't the whole universe. Two other formats matter, plus the hybrid approach that usually wins.

JSON — for structured records, not prose. When the content is data — product specs, pricing tiers, config, API responses — JSON beats both Markdown and HTML. It gives the model explicit key–value structure with minimal ambiguity, and it round-trips cleanly into your application. Use JSON when the answer you need is a field, not a paragraph. Its weakness: JSON for long narrative text is awkward and token-inefficient (lots of quotes, braces, escaping).

XML — verbose, but useful for tagged delimiting. Full XML documents share HTML's bloat problem and are rarely the right content format. But lightweight XML-style tags are genuinely useful as delimiters in prompts — e.g., wrapping untrusted retrieved content in <context>…</context> so the model (and your parser) can tell data from instructions. Use XML tags for structure around content, not as the content format itself.

Hybrid — the approach most production systems land on.

• Markdown for the prose the model reads.
• JSON/metadata for structured fields and provenance (source_url, heading_path, published).
• Sanitized HTML subset only for complex tables Markdown can't express.
• XML-style tags to delimit and label untrusted blocks in the final prompt.

• Markdown — Best at: Prose, docs, code, simple tables — Weak at: Merged-cell tables, rich semantics
• HTML — Best at: Lossless source, complex tables — Weak at: Token bloat, injection surface, noise
• JSON — Best at: Structured records, fields — Weak at: Long narrative text, readability
• XML — Best at: Delimiting/labeling, strict schemas — Weak at: Verbosity as a content format

21. Frequently Asked Questions

1. Is Markdown always better than HTML for LLMs?
For prose, docs, and code — yes, in almost every case, because it delivers more meaning per token with less noise. The exceptions are narrow: complex tables with merged cells, and cases where you need to preserve rich HTML-only semantics (best handled via metadata, not raw HTML).

2. Why do LLMs "understand" Markdown so well?

Because their training corpora are saturated with it — GitHub, docs, Stack Overflow, forums. Markdown structure closely matches the model's learned priors, so headings and lists act as strong, familiar signals.

3. Won't I lose information converting HTML to Markdown?

You lose presentational markup (classes, styles, layout divs) — which is exactly the noise you want gone. You only risk losing semantic signals (dates, canonical URLs, microdata), so capture those into metadata during extraction. Keep raw HTML in storage so conversion is never lossy at the source level.

4. How much can Markdown actually save on tokens?

Commonly 40–70% versus equivalent raw HTML, depending on how markup-heavy the source is. Component-heavy modern pages sit at the high end.

5. Does format affect retrieval accuracy, or just cost?

Both. Format shapes chunk boundaries and embedding quality, which directly move recall@k — not just token bills. That's why you should A/B test formats on your own eval set.

6. Should I store Markdown or HTML?

Store raw HTML as the source of truth; serve Markdown as the projection used for context. Re-project from HTML whenever your pipeline improves.

7. Is converting to Markdown enough to stop prompt injection?

No. It removes many hiding places (scripts, comments, hidden elements), so it's a helpful layer — but you still need defense in depth: separate data from instructions, strip invisible content, and constrain agent tools.

22. Conclusion

The Markdown-vs-HTML question feels like a formatting nitpick, but it's really a decision about how much of every token, every retrieval, and every dollar you spend on signal versus noise.

The evidence points one way for the common case: Markdown is the right default for feeding prose to LLMs. It aligns with how models were trained, it preserves the structure that matters (headings, lists, code, links) while shedding the markup that doesn't, and it does so at a fraction of the token cost. Those savings and quality gains compound across every query for the life of the system.

But the sophisticated answer isn't "Markdown always." It's a layered strategy:

• Store HTML as the lossless, replayable source of truth.
• Serve Markdown as the lean projection your models actually read.
• Rescue HTML-only semantics (dates, canonical, microdata) into structured metadata.
• Fall back to sanitized HTML only for tables Markdown genuinely can't express.
• Reach for JSON when the content is data, not prose — and XML tags to frame untrusted blocks.
• Prove every exception with an eval, because your data is the only benchmark that counts.