--- title: HTML declares a markdown alternate description: "An agent reading the HTML page should be able to discover the markdown mirror without guessing the URL. The standard way to declare it is ``." doc_version: 0.2.0 last_updated: "2026-05-08T23:40:54.245Z" --- ## How the check decides The check queries `link[rel="alternate"][type="text/markdown"]` on the page and asserts a non-empty `href` attribute is present. Fails if no such tag exists. ## How to implement it Emit a `` in your page's `` pointing at the markdown mirror you publish. ### Pass ```html ``` ### Fail ```html ``` ## Common gotchas The href can be **relative** (`/docs/install.md`) or absolute (`https://example.com/docs/install.md`); both satisfy the check. Use whichever your site already prefers for canonical and og links, consistency matters more than the specific form. Make the alternate-link emission part of your shared layout component so it's set automatically on every page. The alternate's URL should be derived from the current page's URL, not duplicated by hand, otherwise you'll forget to update it when adding a new page or moving an existing one. The companion check [`markdown.mirror-suffix`](../markdown.mirror-suffix/) verifies the mirror file actually exists at the URL the alternate-link advertises, so adding the link without publishing the mirror still leaves you with a half-fix. Build your mirror generation and your alternate-link emission together. ## Sitemap Full docs site index: [/sitemap.md](/sitemap.md).