Agent-Friendly Web

Stable URLs and anchors

Pick a simple URL scheme, give every heading a fixed id, and never change either, so agent citations keep working.

Updated

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.

A predictable URL scheme

A good scheme is boring and easy to guess.

The 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.

Explicit heading ids

Many 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.

## Why it matters {#why}
### Edge cases {#edge-cases}

The 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.

<h2 id="why"><a href="#why">Why it matters</a></h2>

Once 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.

Write the policy down

A 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.

ChangeWhat to do
Heading text rewordedKeep the old id
Section removedLeave a short note with the old id, or point to where it went
Page movedServe a permanent redirect, or keep a stub page that says where it went
Page removedKeep a stub page that says it is gone, rather than a silent 404

How this site does it

Every 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. The same ids appear in the anchors list of each JSON record, described in JSON endpoints.