# The HTTP Link rel=alternate Header: What It Is For

> What the HTTP Link header with rel=alternate is, how it announces another version of a URL (another language, a PDF, Markdown) and how to check it arrives.

URL: https://clione.ai/glossary/link-header/
Lang: en

The Link header is not a link you can see on the page or the `<link>` element in the `<head>`, although it says the same thing: it is a line among the response headers, invisible in the browser unless you open its developer tools. It helps a store in three cases. When it has files that are not HTML, such as the technical spec sheet as a PDF, and cannot give them a `<head>`. When it publishes versions in several languages. And when it wants to offer [AI agents](/glossary/ai-agent/) a Markdown version of each page without touching the theme templates. **It is the way to declare relationships between URLs from the server or the CDN**, not from the HTML.

## How it works

The `Link` header is defined by RFC 8288, _Web Linking_, which M. Nottingham published in October 2017 and which replaced RFC 5988. The standard describes a link with four pieces: the context (the URL that responds), the relation type, the target and, if needed, some target attributes. In the header you write the target URL between angle brackets, then `rel` with the relation type and, separated by semicolons, the attributes. **Several links fit in a single header**, separated by commas, or in several `Link` headers in a row.[^rfc8288]

The attributes the standard defines for the target are `hreflang`, a hint about language; `type`, a hint about file type; `media`; `title`; and `anchor`, which changes the link's context. On that last one, the RFC warns that a header with `anchor` is a third-party assertion and cannot be trusted without checking it.[^rfc8288]

`alternate` is one of the relation types registered with IANA, with a one-line description: it refers to a substitute for this context. For the detail, the registry points to the HTML standard.[^iana-link-relations] And there the meaning depends on what accompanies the relation:[^html-alternate]

- With `hreflang` in a language different from the page's, the target is **a translation**.
- With `type`, the target is **a rewording of the same page in another format**. With the RSS or Atom types, it is a syndication feed.
- The two attributes can be combined, for a version in another language and another format at once.

What `alternate` does not say is which of the versions is in charge. For that there is another relation, [canonical](/glossary/canonical-url/), which IANA describes as the one that designates the preferred version of a resource.[^iana-link-relations]

## Three uses on a store

**Languages, with [hreflang](/glossary/hreflang/).** Google supports three ways of telling it the localized versions of a page: elements in the HTML, the sitemap and HTTP headers, and says that **to it the three are equivalent**. The header is the one that works for files that are not HTML, such as PDFs. The rules are the same in all three methods: each version lists itself and all the others, the URLs are fully qualified, with their `https://`, and if two pages do not point at each other, Google ignores the indications. For anyone who fits no language there is the `x-default` value.[^google-hreflang]

**Formats, with type.** The [llms.txt](/glossary/llms-txt/) proposal, in its version of August 10, 2026, asks that pages useful to agents have a clean Markdown version at the same URL with `.md` added, and recommends announcing it with standard relations: `rel="alternate" type="text/markdown"` toward the Markdown version and `rel="describedby"` toward the `llms.txt` that covers it. It proposes it in the HTML or in the header, and points out the advantage of the second: **it is configured on the server or the CDN without modifying any page**.[^llmstxt] It is one of the ways of serving [Markdown for agents](/glossary/markdown-for-agents/). Google, for its part, says there is no need to create machine-readable files, AI text files, markup or Markdown to appear in its Search.[^google-ai-guide] The Markdown version is an offer to agents that want to ask for it, not a Google requirement.

**The canonical of what is not HTML.** The same header carries other relations. Google accepts `rel="canonical"` in the response for files that are not HTML, for example to indicate that the PDF version of a document is the canonical one versus its `.docx`, and only for web search results. It recommends **choosing one method and not mixing it** with the HTML tag, because it is easy to end up declaring one URL in the header and another in the `<link>`.[^google-consolidate]

## On a store

A **fictional example**: a photography store publishes the technical spec sheet of a tripod as a PDF, in Spanish and in English. This is how the Spanish PDF responds:

```text
HTTP/2 200
content-type: application/pdf
link: <https://tienda.example/docs/t20-ficha-es.pdf>; rel="alternate"; hreflang="es", <https://tienda.example/docs/t20-ficha-en.pdf>; rel="alternate"; hreflang="en"
```

The header lists itself and the English version, with fully qualified URLs, and the English PDF has to respond with the same two links. If one of the two does not return the pair, Google ignores both.[^google-hreflang]

The [product page](/glossary/product-page/) of the same tripod, in HTML, announces its Markdown version and the site's `llms.txt`:

```text
HTTP/2 200
content-type: text/html; charset=utf-8
link: </products/travel-tripod-t20.md>; rel="alternate"; type="text/markdown", </llms.txt>; rel="describedby"
```

It is the same shape as the example in the `llms.txt` proposal, with paths relative to the domain.[^llmstxt] The fully qualified URL requirement is Google's for hreflang;[^google-hreflang] for whoever reads this second header, the path is resolved against the URL that responded. Neither line shows on the page: the shopper notices nothing, and whoever reads the headers knows there is another version and where it is.


**alternate and canonical are not interchangeable.** The first refers to a substitute; the second designates the preferred version.[^iana-link-relations] Announcing the Markdown version with `alternate` does not make it the main one, and pointing the product page's canonical at it would say exactly that: that the version you want in the results is the `.md`. The product page's header carries `alternate` toward the Markdown and, if you declare the canonical in the header, the canonical toward the product page itself.


## How to check it

1. **Request the URL with `curl -I`** and look for the lines that start with `link:`. There can be several, or several links separated by commas in one.[^rfc8288]
2. **Look at the same response in the browser**: in the developer tools, Network tab, pick the document and open its response headers.
3. **Open every URL the header announces.** They have to respond with a 200, and in the case of hreflang, each version has to return the same group of links, with fully qualified URLs and itself included.[^google-hreflang]
4. **Check that Google receives the header.** In [Search Console](/glossary/google-search-console/)'s URL Inspection, "Test live URL" and then "View tested page" show the HTTP headers of the response.[^gsc-url-inspection]
5. **If you declare the canonical in the header, make sure it does not clash with the one in the HTML.** Better a single method than two with different URLs.[^google-consolidate]

## Related concept: content negotiation

[Content negotiation](/glossary/content-negotiation/) solves the same thing from the other side. With `alternate`, each version has its own URL and the server announces it; with negotiation, there is a single URL and it is the client who asks for the format in the `Accept` header of its request. Cloudflare applies it in its Markdown for Agents feature: when an agent requests a page with `Accept: text/markdown`, it converts the HTML to Markdown at the edge, responds with `Content-Type: text/markdown` and adds `Accept` to the `Vary` header, so caches store the two versions separately.[^cloudflare-markdown] The two can be combined: a `.md` version with its own URL, announced with `alternate`, and the usual URL serving Markdown to whoever asks for it.

To keep going, the [comparison of the files you offer to search engines and agents](/comparisons/llms-txt-sitemap-structured-data/) puts each in its place, and the [reading path](/learn/crawling-and-indexing/) for this topic puts the rest of the terms in order.