Markdown page versions and link relations

The .md convention

We furthermore propose that pages with information that agents might need provide a clean markdown version of those pages at the same URL as the original page, either with `.md` appended (`page.html.md`) or with the extension replaced by `.md` (`page.md`). (URLs without file names should append `index.html.md` or `index.md` instead.)

Both forms are correct since v2; v1 allowed only the appended form. Pick one per site and use it consistently, so an agent that has guessed one URL can guess the next.

The proposal doesn’t show a URL with no extension and no trailing slash, such as /pricing. Appending .md gives /pricing.md; there is no extension to replace. If your site serves the same page at both /pricing and /pricing/, the link relations below remove the guesswork.

The proposal gives a working example: FastHTML’s by_example.html and its markdown version. It also notes that nbdev projects now create .md versions of all pages by default.

Link relations: alternate and describedby

v2 added these because discoverability was the commonest request after v1: “Given a page, how does an agent find its markdown version, or the llms.txt file that covers it, without guessing?”

To help clients find these files, we recommend using standard link relations: `rel="alternate" type="text/markdown"` points to the markdown version of a page, and `rel="describedby"` points to the llms.txt file that covers it. (An llms.txt file describes all pages under its path, so `/docs/llms.txt` covers everything in `/docs/`.) These links can be provided as HTML `<link>` elements, or as an HTTP `Link:` response header. The header form also works for non-HTML resources, such as the markdown files themselves, and can be added in web server or CDN configuration without modifying any pages.

The HTTP Link header

The proposal’s example, for a page at /docs/page.html covered by /docs/llms.txt:

Link: </docs/page.html.md>; rel="alternate"; type="text/markdown", </docs/llms.txt>; rel="describedby"

Two links, separated by a comma, in one header (the syntax is RFC 8288, Web Linking). The markdown file itself has no alternate, so its response carries only the second link:

Link: </docs/llms.txt>; rel="describedby"

The header is the only form that works on a markdown or text file, and the only one you can add without editing pages.

The HTML link element

The same two links, in the <head> of /docs/page.html. The proposal names this form but doesn’t print an example; this is the standard <link> syntax for the relations it names:

<link rel="alternate" type="text/markdown" href="/docs/page.html.md">
<link rel="describedby" href="/docs/llms.txt">

The proposal says the links “can be provided” in either form; it doesn’t require both. The header reaches clients that don’t parse HTML; the element survives when a page is saved or cached without its headers.

Why it matters for agents

• Cheaper, cleaner reading. The proposal’s case for llms.txt is that HTML wraps information in navigation, ads and JavaScript. A markdown version skips all of that.
• No guessing. Without the links, an agent has to try page.html.md, then page.md, then give up. With them, one response tells it where both files are.
• Entry from anywhere. An agent that arrives on a deep page from a search result can follow describedby up to the llms.txt that covers it, and so to the rest of your curated links.
• Better llms.txt links. v2 says the links in llms.txt should point to LLM-friendly content. Markdown versions are the obvious target.

How to add them

1. Generate the markdown versions. Most docs tools and static site generators start from markdown, so the build can write each page’s source next to its HTML. Some platforms do it for you: llmstxt.org lists Mintlify as generating markdown page versions for every site it hosts, and nbdev does it by default.
2. Serve them as markdown. The proposal doesn’t name a Content-Type for these files. text/markdown is the registered media type (RFC 7763), and it is the type the alternate link names.
3. Add the links in one place. In a site template, put the two <link> elements in the shared <head>. On a web server or CDN, add a Link response header by path pattern. In a framework, use its response-header configuration.
4. Check them. Fetch a page with curl -sI https://yoursite.com/page and look for the Link header, then fetch the URL it names. The markdown versions checker runs the same checks across the pages your llms.txt links.

In Next.js, for example, headers() in next.config can attach the header per route:

// next.config.mjs
export default {
  async headers() {
    return [
      {
        source: '/pricing',
        headers: [
          {
            key: 'Link',
            value: '</pricing.md>; rel="alternate"; type="text/markdown", </llms.txt>; rel="describedby"',
          },
        ],
      },
    ];
  },
};

What llmsrank.dev does

We publish these links ourselves, from one shared module so the headers and the markdown files can’t drift apart:

Each markdown version answers with describedby pointing to /llms.txt, plus rel="canonical" pointing back to its HTML page so search engines don’t treat it as a duplicate. The canonical link is our choice; the proposal doesn’t mention search engines or canonical URLs.

Sources

• llmstxt.org — The /llms.txt file, v2 (modified 2026-08-10)
• llmstxt.org — The /llms.txt file, v2, markdown version
• llmstxt.org — Changes: v2 (August 2026)
• RFC 8288 — Web Linking (the HTTP Link header)
• RFC 7763 — The text/markdown media type

Related

• About llms.txt
• Writing an llms.txt file
• llms.txt release notes