Skip to content

PATTERN Cited by 1 source

link rel="alternate" markdown discovery

Pattern

Embed a standard HTML <link rel="alternate"> tag in every page's <head> advertising the markdown version of the site's content, so an agent that fetched HTML can discover the markdown alternative by parsing the HTML head without needing to know any site-specific convention.

Canonical shape (from Vercel's 2026-04-21 post):

<link rel="alternate"
      type="text/markdown"
      title="LLM-friendly version"
      href="/llms.txt" />

The tag is a standards-based cooperative signal that sits alongside Accept-header content negotiation and URL-based conventions as an orthogonal discovery mechanism.

Why it exists

Three agent-capability gaps motivate the pattern:

  1. Header-less agents — many agents in 2026 fetch HTML without sending Accept: text/markdown. Checkly's 2026-02 research found only 3 of 7 tested agents send the header by default. An agent that landed on the HTML version by accident needs a way to discover the markdown version.
  2. URL-convention-ignorant agents — agents that don't probe for /index.md or /<path>/sitemap.md need the server to tell them the markdown URL.
  3. Standard HTML head parsing — agents that follow basic HTML conventions (Open Graph tags, canonical links, RSS alternate links) already parse <head> for <link rel="..."> tags; adding a markdown alternate fits the pattern they already follow.

The <link rel="alternate"> element is a W3C standard going back to HTML 4.0; every parser supports it. The type="text/markdown" attribute piggybacks on the MIME type (RFC 7763) to communicate format.

Three-layer agent discovery stack

Vercel's 2026-04-21 post presents this pattern as the third layer of a layered discovery stack:

Layer Mechanism Prerequisite on agent
1 Accept: text/markdown request header Agent knows to send the header
2 Markdown sitemap at /<section>/sitemap.md Agent fetches sitemap
3 <link rel="alternate" type="text/markdown" href="/llms.txt"> Agent parses HTML <head>

Each layer covers a different agent-implementation gap. Layer 3 is the safety net — if the agent fetched HTML, at least give it a pointer to the markdown source.

Where the href points

Two common target choices:

Point at /llms.txt — Vercel's example. The agent gets a curated agent-optimised content index (see concepts/llms-txt), from which it can pick specific pages to fetch with Accept: text/markdown. Composes naturally with the header-based layer.

Point at the per-page markdown URL (e.g. /blog/<slug>.md or /blog/<slug>/index.md). Per-page specificity; agent gets the markdown for the current page rather than a site-wide index. Requires the site to expose a stable per-page markdown URL (conflicts with Vercel's "we don't want URL conventions" argument, but both layers can coexist).

Point at a markdown sitemap (e.g. /blog/sitemap.md). Intermediate option; agent gets a structured enumeration of available markdown content.

Sites typically pick one and advertise it consistently across pages. Advertising multiple <link rel="alternate"> tags (one per markdown target) is spec-legal and lets the agent pick.

Composition with siblings

  • + Accept: text/markdown (patterns/accept-header-rewrite-to-markdown-route) — ideal flow. Agent sees the <link rel="alternate">, learns markdown is available, next turn sends the header, gets efficient markdown back. Best path for clients that initially fetched HTML.
  • + /index.md URL fallback (patterns/dynamic-index-md-fallback) — agent reads href from <link rel>, follows the URL; URL-rewrite rules serve markdown at that path. Both mechanisms at once.
  • + llms.txt — href="/llms.txt" gives the agent a curated index rather than a single page's markdown; pair with per-entry <page>/index.md links in llms.txt.
  • + Hidden agent directive in HTML — complementary. The hidden directive says "fetch markdown next time" in prose; <link rel="alternate"> says "here's where" in standards-based markup. Both in the same page means both cooperative-agent-parsers and LLM-direct-prose- followers get the signal.

Failure modes and caveats

  • Agent must parse <head>. Some agents slurp response body to a text-extraction pipeline that skips <head>. Those agents won't see the hint. The hidden-agent-directive-in-html pattern complements this failure mode with a prose hint inside the body.
  • Not an enforcement mechanism. The tag is advisory; agents can ignore it. For adversarial scrapers, rely on rate limiting, bot-detection, or legal/contractual controls.
  • href staleness. If the agent caches the <link rel="alternate"> URL, then the site moves the markdown endpoint, the agent will 404. Mitigation: keep the markdown-URL scheme stable, use HTTP 301 redirects on moves.
  • No standard IANA-registered type for the LLM- optimised variant. text/markdown is the right MIME type but doesn't distinguish "markdown optimised for LLMs" from "raw markdown source with LLM-unfriendly custom extensions". No such distinction exists today in MIME; agents must trust the site to serve LLM- friendly markdown.
  • title attribute is informational-only. Not machine-consumed in practice. Vercel uses "LLM-friendly version" as a human hint.

Portability

The pattern is a single HTML tag — portable to any static or dynamic site generator:

  • Jekyll / Hugo / 11ty / Astro: layout templates include the tag in the <head>.
  • Next.js: app/layout.tsx <head> includes the <link> or uses metadata exports.
  • WordPress / Ghost / generic CMS: theme header template includes the tag.
  • Plain HTML: hand-add to every page's <head>.

No runtime logic required; the tag is declarative.

Adoption signal

Vercel's blog uses this pattern pointed at /llms.txt as of 2026-04-21 — aligned with the site's markdown content negotiation + markdown sitemap primitives. The pattern is not (yet) scored as a dimension of the Agent Readiness Score but is consistent with its "Content for LLMs" category.

Seen in

Last updated · 476 distilled / 1,218 read