Product markdown-mirror template

Version 1.1 · Last verified 2026-07-08

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.

Key takeaways

• 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).

# {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. 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.Hypothesis (our analysis) The same discipline drives our information density chapter, which argues the case in full.

The mechanical reason to strip weight is not ours. 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.ReportedCloudflare, Mintlify, and Vercel agent-Markdown guides (2026) 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 blueprint for the machine-parseable version of the same facts, and with make your 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. 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.ReportedPronovix, How to serve Markdown to AI agents (2026-03-24) 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. 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.Spec-factMDN, HTTP content negotiation

This blueprint ships the distinct-URL variant. 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.Hypothesis (our analysis)

Whichever you pick, advertise the alternate so agents that cannot negotiate can still find it. Vercel recommends advertising the Markdown alternate with a <link rel="alternate"> element so an agent that cannot negotiate can still find it.ReportedVercel, Making agent-friendly pages with content negotiation (2026-02-03) 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:

<!-- 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}" />

The honest boundary

Ship the mirror because it is cheap and standards-compliant, not because it is proven to win selection. 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.Hypothesis (our analysis) 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. 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.Spec-factGoogle, Optimizing your website for generative AI features on Google Search 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 blueprint; for the site-level index that points agents at your catalog, see llms.txt for e-commerce catalogs; and for serving these surfaces fast at the edge, see edge-worker config for machine surfaces. The reasoning behind the ordering sits in information density.

Version 1.1

• 2026-07-08, v1.1: Re-verified 2026-07-08 that no named shopping agent documents fetching product Markdown, and added Google's AI-optimization-guide statement as a sourced claim in the honest-boundary section.
• 2026-07-08, v1.0: Initial publication.