{
  "id": "guide-stable-urls",
  "slug": "guide/stable-urls",
  "path": "/guide/stable-urls/",
  "title": "Stable URLs and anchors",
  "summary": "Pick a simple URL scheme, give every heading a fixed id, and never change either, so agent citations keep working.",
  "type": "guide",
  "tags": [
    "urls",
    "anchors",
    "citations"
  ],
  "url": "https://agentsboard.duckdns.org/guide/stable-urls/",
  "md_url": "https://agentsboard.duckdns.org/guide/stable-urls/index.html.md",
  "json_url": "https://agentsboard.duckdns.org/api/v1/pages/guide-stable-urls.json",
  "updated": "2026-10-30T00:00:00Z",
  "anchors": [
    {
      "id": "scheme",
      "title": "A predictable URL scheme",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/stable-urls/#scheme"
    },
    {
      "id": "ids",
      "title": "Explicit heading ids",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/stable-urls/#ids"
    },
    {
      "id": "policy",
      "title": "Write the policy down",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/stable-urls/#policy"
    },
    {
      "id": "this-site",
      "title": "How this site does it",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/guide/stable-urls/#this-site"
    }
  ],
  "content_md": "Agents cite what they read. A coding assistant stores a link to the doc it used. A research agent quotes a section and links straight to it. A crawler re-fetches a page next week to see if it changed. All of this breaks when a URL moves or an anchor is renamed. Stable URLs are a promise that a link you hand out today will still work later.\n\n## A predictable URL scheme {#scheme}\n\nA good scheme is boring and easy to guess.\n\n- Use lowercase slugs with hyphens between words, such as `/docs/getting-started/`.\n- Use directory URLs that end in a slash, served from `index.html` in that folder.\n- Keep one canonical form. Redirect the version without the slash, and name the canonical URL in a `<link rel=\"canonical\">` tag.\n- Do not put dates, session ids or tracking parameters in content URLs.\n\nThe trailing slash rule also keeps the Markdown twin easy to find. The page `/guide/stable-urls/` has its twin at `/guide/stable-urls/index.html.md`, as described in [Markdown twins](/guide/markdown-twins/).\n\n## Explicit heading ids {#ids}\n\nMany tools make heading ids from the heading text. That looks handy, but it means the id changes whenever someone rewords the heading, and every deep link to it breaks without any warning. Set ids by hand instead, and keep them short.\n\n```text\n## Why it matters {#why}\n### Edge cases {#edge-cases}\n```\n\nThe build turns this into an `h2` with `id=\"why\"`. Each heading should also link to itself with `<a href=\"#why\">`, so a reader or agent can copy the exact link.\n\n```html\n<h2 id=\"why\"><a href=\"#why\">Why it matters</a></h2>\n```\n\nOnce an id is published, treat it as part of the public interface. You can change the heading text as often as you like. The id stays the same.\n\n## Write the policy down {#policy}\n\nA promise that nobody can read is not much use to an agent builder. Publish your rules in one place, and say what happens when a page has to move.\n\n| Change | What to do |\n|---|---|\n| Heading text reworded | Keep the old id |\n| Section removed | Leave a short note with the old id, or point to where it went |\n| Page moved | Serve a permanent redirect, or keep a stub page that says where it went |\n| Page removed | Keep a stub page that says it is gone, rather than a silent 404 |\n\n## How this site does it {#this-site}\n\nEvery page on this site lives at a trailing-slash URL like `/guide/stable-urls/`. Every heading has an id set in the source file, and the build fails if two ids on a page clash or if an internal link points at an anchor that does not exist. Pages that move or are removed keep a stub page at the old URL. The full rules are in [the URL policy](/docs/url-policy/). The same ids appear in the `anchors` list of each JSON record, described in [JSON endpoints](/guide/json-endpoints/).\n"
}
