{
  "id": "guide-markdown-twins",
  "slug": "guide/markdown-twins",
  "path": "/guide/markdown-twins/",
  "title": "Markdown twins",
  "summary": "Publish a Markdown copy of every HTML page at a predictable URL so agents get clean content without page chrome.",
  "type": "guide",
  "tags": [
    "markdown",
    "content"
  ],
  "url": "https://agentsboard.duckdns.org/guide/markdown-twins/",
  "md_url": "https://agentsboard.duckdns.org/guide/markdown-twins/index.html.md",
  "json_url": "https://agentsboard.duckdns.org/api/v1/pages/guide-markdown-twins.json",
  "updated": "2026-10-25T00:00:00Z",
  "anchors": [
    {
      "id": "where",
      "title": "Where the twin lives",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/markdown-twins/#where"
    },
    {
      "id": "discoverable",
      "title": "Making the twin discoverable",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/markdown-twins/#discoverable"
    },
    {
      "id": "serving",
      "title": "Serving it correctly",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/markdown-twins/#serving"
    },
    {
      "id": "sync",
      "title": "Keeping twins in sync",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/markdown-twins/#sync"
    }
  ],
  "content_md": "HTML pages carry navigation, footers, styles and scripts. A person skips past them without thinking. An agent has to parse them, and every extra token costs space in its context window. A Markdown twin is a second copy of the same page with only the content, in a format that language models read well.\n\n## Where the twin lives {#where}\n\nThe llms.txt proposal sets out a simple URL rule, so an agent can find the twin without being told.\n\n| HTML URL | Markdown twin |\n|---|---|\n| `/page.html` | `/page.html.md` |\n| `/docs/start/` | `/docs/start/index.html.md` |\n| `/guide/llms-txt/` | `/guide/llms-txt/index.html.md` |\n\nA directory URL ending in a slash is served from `index.html`, so its twin is `index.html.md` in the same folder. Some sites also accept `/page.md`, but pick one pattern and use it everywhere.\n\n## Making the twin discoverable {#discoverable}\n\nThe URL rule lets a well-informed agent guess the twin. A link tag in the HTML head tells every other agent where it is.\n\n```html\n<link rel=\"alternate\" type=\"text/markdown\" href=\"/guide/markdown-twins/index.html.md\">\n<link rel=\"describedby\" href=\"/llms.txt\">\n```\n\nThe first tag points at the twin. The second points at the site index described in [The llms.txt file](/guide/llms-txt/). Both are plain markup, so they work without JavaScript.\n\nDo not rely on content negotiation. On a static host there is no way to answer an `Accept: text/markdown` header with a different file. Use URL conventions instead. If you control the server, you can add a `Link:` response header as an extra hint.\n\n## Serving it correctly {#serving}\n\nThe twin is only useful if it arrives as text. A server that does not know the `.md` extension may send it as `application/octet-stream`, and the browser will download it instead of showing it. Map the type explicitly.\n\n```nginx\ntypes {\n    text/markdown  md;\n}\ncharset utf-8;\ncharset_types text/markdown text/plain application/json;\n```\n\nThe `charset` part matters too. Without it, curly quotes and dashes can turn into mojibake.\n\n## Keeping twins in sync {#sync}\n\nThe biggest risk with twins is drift. If someone fixes a typo in the HTML and forgets the Markdown, the two copies now disagree, and an agent may quote the wrong one. The fix is to generate both from a single source:\n\n- Write each page once, in Markdown with front-matter.\n- Have the build render the HTML and copy the cleaned Markdown next to it.\n- Emit the JSON record and the sitemap entry in the same pass.\n\nOn this site every page has a twin. For example, this page is at `/guide/markdown-twins/` and its twin is at `/guide/markdown-twins/index.html.md`. You can read the full list of machine formats in [the endpoint reference](/docs/endpoints/), and see how content files are written in [the authoring docs](/docs/authoring/). For the data side, see [JSON endpoints](/guide/json-endpoints/).\n"
}
