# Product markdown-mirror template

> A product markdown mirror is a plain .md copy of a product page ordered by decision weight: identifiers, specs, price, availability, shipping and returns first, marketing prose last or omitted. Copy the template below.

<!-- A copy-paste per-product Markdown mirror template, ordered by decision weight so AI shopping agents read the facts that drive selection first. -->
<!-- Canonical: https://agentmint.net/blueprints/product-markdown-mirror/ · Blueprint v1.1 · By Abdalsalaam Halawa · Published 2026-07-08 · Last verified 2026-07-08 -->
<!-- Evidence tags below are load-bearing: <Claim type="spec-fact|reported|hypothesis"> marks how each factual claim is sourced. -->

A product markdown mirror is a distinct `.md` URL that serves a plain-Markdown copy of a product page, ordered so the facts an agent selects on, identifiers, specs, price, availability, shipping, and returns, come first and marketing prose comes last or not at all. This blueprint is the template plus the judgment about what goes where and why.

<KeyTakeaways
  items={[
    "A product markdown mirror is a distinct .md URL serving a plain-Markdown copy of a product page. It is a valid, conservative machine surface: no Accept-header branching, it caches and links like any other URL, and it stays discoverable through a rel=alternate reference.",
    "Order the mirror by decision weight: identifiers, specs, price, availability, shipping, and returns first; marketing prose last or omitted. That ordering is our inference from the facts-per-token principle, not a rule any vendor publishes.",
    "Same-URL content negotiation and distinct .md mirrors are complementary, not rivals. AgentMint ships distinct mirrors as a conservative choice, not a safer one.",
    "The mirror is only safe if its facts equal the HTML a shopper sees. Different content by format is legitimate; different content by audience is cloaking. And no verified source shows a shopping agent fetches product Markdown yet, so ship it cheaply but do not attribute a selection outcome to it.",
  ]}
/>

## The template

Copy this per product. Replace every `{placeholder}`, keep the section order, and delete any section you cannot fill honestly rather than padding it. Serve it at a stable `.md` URL alongside the HTML page (for example `/product/weighted-sleep-mask.md`).

```markdown
# {Product name}

> {One factual sentence: what it is, the headline spec, price, and availability.}

## Identifiers
- GTIN: {gtin13}
- MPN: {manufacturer part number}
- SKU: {your internal sku}
- Brand: {brand name}
- Condition: {New | Refurbished | Used}

## Specifications
- {Spec name}: {value with unit}
- {Spec name}: {value with unit}
- Material: {material}
- Dimensions: {L x W x H with unit}
- Weight: {value with unit}

## Price
- Price: {24.99} {USD}
- Price valid until: {2026-12-31}

## Availability
- Availability: {In stock | Out of stock | Preorder | Backorder}
- Sold by: {seller name}
- Ships from: {country}

## Shipping
- Shipping cost: {0.00} {USD}
- Ships to: {US, CA, GB}
- Handling time: {1-2 business days}
- Transit time: {2-3 business days}

## Returns
- Return window: {30 days | not accepted}
- Return method: {by mail | in store}
- Return fees: {free | customer pays}

## Description
{Optional. One short factual paragraph only. Omit brand-voice copy.}

---
Canonical: https://example.com/product/{slug}
Last updated: {2026-07-08}
```

## Why this order

The ordering is the load-bearing decision in the template, and it is ours, not a vendor's. <Claim type="hypothesis">We order the mirror by decision weight, leading with identifiers, then specifications, price, availability, and shipping and returns, and pushing any description to the end or out entirely, because structured verifiable facts plausibly carry more decision weight per token than qualitative marketing prose. Those are the fields an agent can match against a shopper's query and compare across stores; a sentence of adjectives is expensive to read and hard to act on.</Claim> The same discipline drives our [information density](/handbook/information-density/) chapter, which argues the case in full.

The mechanical reason to strip weight is not ours. <Claim type="reported" source="Cloudflare, Mintlify, and Vercel agent-Markdown guides" date="2026" href="https://vercel.com/blog/making-agent-friendly-pages-with-content-negotiation">Vendors publishing guidance on serving Markdown to agents through 2026, including Cloudflare, Mintlify, and Vercel, each state that agents operate under context-window and token budgets, and that converting HTML to Markdown reduces token consumption and cost while preserving the decision-relevant content.</Claim> A mirror that opens with a GTIN and a price spends the agent's budget on facts; one that opens with a paragraph of brand copy spends it on nothing the agent can use.

The identifiers block leads for a reason beyond density: it is what lets an agent resolve your listing to a specific product across catalogs. Put the same identifiers, specs, price, availability, and policies into your structured channels too, since a mirror is not a substitute for them. Pair this template with the [token-efficient product JSON-LD](/blueprints/token-efficient-product-json-ld/) blueprint for the machine-parseable version of the same facts, and with [make your product feed AI-readable](/make-product-feed-ai-readable/) for the merchant-controlled data an engine ingests directly.

## Why a distinct .md URL

There are two documented ways to hand an agent a Markdown copy, and they are complementary. <Claim type="reported" source="Pronovix, How to serve Markdown to AI agents" date="2026-03-24" href="https://pronovix.com/articles/how-serve-markdown-ai-agents-without-breaking-your-seo">Pronovix, writing in March 2026, frames same-URL Accept-header negotiation and distinct .md URLs as complementary rather than competing, and recommends pairing the Markdown alternate with a canonical link so search engines still consolidate on the HTML page.</Claim> The alternative to a distinct URL is same-URL negotiation, where one URL returns HTML by default and Markdown when the request sends `Accept: text/markdown`. <Claim type="spec-fact" source="MDN, HTTP content negotiation" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Content_negotiation">MDN defines content negotiation as "the mechanism that is used for serving different representations of a resource to the same URI," selected by the client's Accept header.</Claim>

This blueprint ships the distinct-URL variant. <Claim type="hypothesis">AgentMint itself serves distinct .md mirror URLs rather than same-URL negotiation, and we treat that as a valid, conservative choice, not a safer one: it needs no Accept-header branching at the edge, it caches and links like any other URL, and it stays discoverable through a rel=alternate reference. Same-URL negotiation is equally legitimate; the two are implementation options, not a safety ranking, and no source we verified ranks one above the other.</Claim>

Whichever you pick, advertise the alternate so agents that cannot negotiate can still find it. <Claim type="reported" source="Vercel, Making agent-friendly pages with content negotiation" date="2026-02-03" href="https://vercel.com/blog/making-agent-friendly-pages-with-content-negotiation">Vercel recommends advertising the Markdown alternate with a `<link rel="alternate">` element so an agent that cannot negotiate can still find it.</Claim> Add these two lines to the HTML product page head and keep the canonical pointing at the HTML page so ranking signals stay consolidated there:

```html
<!-- In the HTML product page <head> -->
<link rel="alternate" type="text/markdown" href="https://example.com/product/{slug}.md" />
<link rel="canonical" href="https://example.com/product/{slug}" />
```

<Callout variant="warning" title="Equivalence guard: keep the mirror's facts equal to the HTML">
  A markdown mirror is safe because it is a different format of the same content, not different content for a different audience. <Claim type="spec-fact" source="Google, Spam policies for Google web search" href="https://developers.google.com/search/docs/essentials/spam-policies">Google defines cloaking as "the practice of presenting different content to users and search engines with the intent to manipulate search rankings and mislead users."</Claim> <Claim type="hypothesis">We read a Markdown mirror whose facts equal the HTML as format negotiation rather than cloaking, because cloaking turns on serving different content with intent to deceive, whereas the mirror delivers the same facts in a machine-preferred representation. It becomes a cloaking risk the moment a price, claim, or spec appears in the mirror but not in the HTML a shopper sees.</Claim> The full argument lives in the [information density](/handbook/information-density/) chapter; here the rule is short: any fact present in one and absent from the other is a defect, fix it so the two are equivalent.
</Callout>

## The honest boundary

Ship the mirror because it is cheap and standards-compliant, not because it is proven to win selection. <Claim type="hypothesis">We have found no verified public source showing that a shopping agent (ChatGPT Shopping, Perplexity, or Gemini) fetches a Markdown representation of a product page. Treat content negotiation and .md mirrors as proven for documentation and coding agents and unverified for shopping agents, and do not attribute a selection outcome to the mirror.</Claim> Re-verified 2026-07-08: no named shopping agent (ChatGPT Shopping, Perplexity, or Google's Gemini and AI Mode) documents fetching product Markdown or negotiating a Markdown representation of a product page; the crawler documentation OpenAI, Perplexity, and Anthropic publish describes robots.txt as the control mechanism and never mentions Markdown negotiation, and OpenAI's Agentic Commerce product feed spec describes a structured feed file, not page-format negotiation. <Claim type="spec-fact" source="Google, Optimizing your website for generative AI features on Google Search" href="https://developers.google.com/search/docs/fundamentals/ai-optimization-guide">Google's AI-features optimization guide, updated in June 2026, states that sites do not need to create new machine-readable files, AI text files, markup, or Markdown to appear in Google Search, and that Google Search ignores such files.</Claim> All of that is absence of documentation as of that date, not proof that no agent ever fetches Markdown. If your products are missing from an engine's results, the format of an alternate representation is far down the list of likely causes.

## Verify before you ship

- First-screen facts. Read the first 200 words of the rendered mirror and count the verifiable facts (identifier, spec, price, availability, policy). If the count is low because a description leads, reorder so the identifiers and specs come first.
- Equivalence diff. Compare every fact in the mirror against the HTML product page. Any price, claim, or spec present in one and absent from the other is a cloaking risk, not a shortcut.
- Discoverability. Confirm the HTML page exposes a `<link rel="alternate">` to the `.md` mirror and a `<link rel="canonical">` to itself, so agents can find the format and search engines still consolidate on the page.
- Freshness. Confirm the mirror regenerates when the product's price, availability, or policy changes, so a stale mirror never contradicts the live page.

For the machine-parseable version of these same facts, continue with the [token-efficient product JSON-LD](/blueprints/token-efficient-product-json-ld/) blueprint; for the site-level index that points agents at your catalog, see [llms.txt for e-commerce catalogs](/blueprints/llms-txt-for-ecommerce-catalogs/); and for serving these surfaces fast at the edge, see [edge-worker config for machine surfaces](/blueprints/edge-worker-machine-surfaces/). The reasoning behind the ordering sits in [information density](/handbook/information-density/).