# Markdown page versions and link relations

Alongside llms.txt, the proposal asks pages that agents might need to offer a clean markdown version at a predictable URL. Since v2 (August 2026) it also recommends standard link relations so an agent that lands on a page can find that markdown version, and the llms.txt that covers the page, without guessing. This page sets out both conventions as the proposal words them, shows the HTML and HTTP header forms, and explains how to add them.

Updated 2026-09-28. This is the markdown version of https://llmsrank.dev/learn/markdown-pages.

## 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.)
>
> Source: [llmstxt.org — The /llms.txt file, v2 (modified 2026-08-10)](https://llmstxt.org/)

| Page URL | `.md` appended | Extension replaced |
|---|---|---|
| `/docs/quickstart.html` | `/docs/quickstart.html.md` | `/docs/quickstart.md` |
| `/docs/` (no file name) | `/docs/index.html.md` | `/docs/index.md` |
| `/` (no file name) | `/index.html.md` | `/index.md` |

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](https://www.fastht.ml/docs/tutorials/by_example.html) and its [markdown version](https://www.fastht.ml/docs/tutorials/by_example.html.md). 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.
>
> Source: [llmstxt.org — The /llms.txt file, v2 (modified 2026-08-10)](https://llmstxt.org/)

| Relation | Points to | Put it on |
|---|---|---|
| `rel="alternate" type="text/markdown"` | The markdown version of this page | HTML pages that have a markdown version |
| `rel="describedby"` | The llms.txt file that covers this page | Any page or file covered by an llms.txt, including the markdown versions themselves |

## The HTTP Link header

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

```http
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:

```http
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:

```html
<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](https://llmsrank.dev/tools/markdown-versions) 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:

```js
// 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"',
          },
        ],
      },
    ];
  },
};
```

> **Caution: Don’t advertise a 404.** Only send `rel="alternate"` for pages whose markdown version exists. Pointing agents at a missing file is worse than pointing them at nothing. `rel="describedby"` is safe anywhere an llms.txt covers the page.

## What llmsrank.dev does

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

| Page | Markdown version | Link header |
|---|---|---|
| `/` | `/index.md` | `</index.md>; rel="alternate"; type="text/markdown", </llms.txt>; rel="describedby"` |
| `/bot` | `/bot.md` | `</bot.md>; rel="alternate"; type="text/markdown", </llms.txt>; rel="describedby"` |
| `/scan/<id>` (a report) | `/scan/<id>.md` | alternate and describedby, as above |
| `/learn` and each guide, including this one | `/learn.md`, `/learn/<guide>.md` | alternate and describedby, as above |
| `/docs/…` | Not yet | `</llms.txt>; rel="describedby"` only |

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.

> **Note: How LLMSRank scores this.** LLMSRank’s rubric audit [Markdown versions](https://llmsrank.dev/docs/audits/markdown-versions) checks whether the pages your llms.txt links to have markdown versions. It currently tries the appended form (`page.html.md`, `index.html.md`); recognising the replaced form, and scoring link relations, is planned. Link relations are not scored yet.

## Frequently asked questions

### Which is correct, page.html.md or page.md?

Both, since v2. v1 allowed only `.md` appended to the full URL (`page.html.md`); v2 also allows the extension replaced by `.md` (`page.md`).

### What is the markdown URL for a page without a file name, like /docs/?

Append `index.html.md` or `index.md`: `/docs/index.html.md` or `/docs/index.md`.

### Do I need both the HTML link element and the Link header?

No. The proposal says the links can be provided either way. The header also works for non-HTML files, such as the markdown versions themselves, and can be added in server or CDN configuration without editing pages.

### What does rel="describedby" point to?

The llms.txt file that covers the page: the most specific one whose path contains it, such as `/docs/llms.txt` for a page under `/docs/`.

### What Content-Type should markdown versions use?

The proposal doesn’t say. `text/markdown` is the registered media type, and it is the type named in the `rel="alternate"` link.

### Will markdown versions count as duplicate content in search?

The proposal doesn’t address search engines. llmsrank.dev sends a `rel="canonical"` Link header on each markdown version pointing back to its HTML page; that is one option, not part of the proposal.

## Sources

- [llmstxt.org — The /llms.txt file, v2 (modified 2026-08-10)](https://llmstxt.org/)
- [llmstxt.org — The /llms.txt file, v2, markdown version](https://llmstxt.org/index.md)
- [llmstxt.org — Changes: v2 (August 2026)](https://llmstxt.org/changes.html)
- [RFC 8288 — Web Linking (the HTTP Link header)](https://datatracker.ietf.org/doc/html/rfc8288)
- [RFC 7763 — The text/markdown media type](https://datatracker.ietf.org/doc/html/rfc7763)

## Related

- [About llms.txt](https://llmsrank.dev/learn/llms-txt.md)
- [Writing an llms.txt file](https://llmsrank.dev/learn/writing-llms-txt.md)
- [llms.txt release notes](https://llmsrank.dev/learn/release-notes.md)