--- 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-04-24T21:30:56.217Z" --- ## 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).