Markdown alternate links: what the check tests and how to fix it

Passes when a crawled page has <link rel="alternate" type="text/markdown"> in its HTML. An HTTP Link header with the same relation is not detected.

Agent Discovery · Weight 0.5 in the w2agent Score

How common is it?

16% of 1223 measured sites where this check applied pass.

Latest audit of each site under rubric v3.1. Sites where the check did not apply or could not be measured (for example, no llms.txt for the llms.txt checks) are left out. A partial result does not count as a pass.

What this check tests

For each page the audit crawled (the homepage and a sample of other pages), it parses the HTML and looks for <link rel="alternate"> elements that have both a type and an href, and whose type contains the word "markdown" (so text/markdown matches).

  • Pass: at least one crawled page has such a link.
  • Fail: none do.
  • The score is 25 points per page with a markdown alternate, capped at 100. Any page counts for a pass, so the status is pass while the score still reads 25, 50 or 75.

The check does not fetch the linked address, so it does not know whether the markdown exists. Whether the markdown is actually served is tested by content negotiation (Markdown). It also reads only the HTML <link> element. The proposal also shows the same relation sent as an HTTP Link header, and a header-only setup is not detected here.

Why it matters to agents

An agent that fetches a page gets the whole HTML document: navigation, scripts and markup around the text it wants. A pointer to a clean markdown version lets it fetch just the content. The llms.txt proposal recommends that pages with information agents may need offer a markdown version at the same URL with .md added, and suggests the standard rel="alternate" type="text/markdown" link relation so clients can find it. text/markdown is the registered media type for Markdown (RFC 7763), and RFC 8288 describes alternate as a registered link relation type and defines how links are sent in the HTTP Link header.

This is a convention that tools may or may not use. It is cheap, and it is useful mainly for documentation sites that already generate markdown.

How to fix it

First make sure the markdown version exists, then link to it from the page head.

<head>
  <link rel="alternate" type="text/markdown" href="/docs/getting-started.md" />
</head>
  • Serve the markdown with Content-Type: text/markdown; charset=utf-8 at the address in href. Your HTML pages should declare their encoding too; see UTF-8 charset.
  • Emit the link on every page that has a markdown twin, not only the homepage; the score rises with the number of crawled pages that carry it.
  • Docs generators and CMS themes often have a hook for head tags. Check yours before editing templates by hand.
  • If you also serve markdown through the Accept header, see content negotiation for the Vary header you need.

Related: llms.txt exists, which links to the same markdown pages.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →