The orphan page problem, and why we derive links instead of writing them

Here is a failure mode that shows up in almost every programmatic site, including sites built by careful people.

You write page A and link it to pages B and C, because you are thinking about A. Later you write page D and link it to B. Nobody ever goes back to B to link it to D. Repeat four hundred times and a large share of your pages have zero inbound links from anywhere except a hub, which is the weakest possible position for a page to be in.

The links exist. They point one way.

Why this is worse than it sounds

A page with no inbound contextual links is a page the crawler reaches only through a paginated index, competing for attention with everything else on that index. It is also a page no reader ever arrives at from a related page, which is the traffic that actually converts, because the reader is already in the subject.

The usual remedy makes it worse: a footer listing every URL on the site. That gives every page an inbound link, technically, and it gives the crawler a flat undifferentiated blob with no signal about what relates to what.

What we do instead

Our link graph is derived at build time, never authored.

A page declares what it is related to, in one direction only: a tutorial names its tool, a prompt names two other prompts, a competitor names two competitors. The build reads every published record, constructs the graph, and then computes the reverse edges.

So when we publish a new tutorial that names Linear, Linear’s page gains an inbound link to it in the same deploy. Nobody edits Linear’s page. Nobody remembers to. The edge exists because the relationship exists.

Two properties fall out of this that we did not fully appreciate until it was running:

The graph is built from live pages only. Reverse edges are computed after the publication gate runs, so a draft record contributes nothing. Linking to a page that does not exist is worse than not linking, and this makes it structurally impossible rather than a thing to check.

Minimum inbound degree becomes satisfiable. We require every page to have at least three inbound links before it is allowed to publish. With authored links that requirement is either ignored or gamed. With derived links it is a statement about whether the page is actually connected to anything, and a page that fails it is telling you something true: it does not belong to the rest of the site yet.

The check that caught us

We have a build gate that walks the rendered output and reports any page below the inbound threshold. The week we added our blog, it failed:

FAIL  1 orphan(s) with fewer than 1 inbound link(s):
    /blog/ (0)

We had built the hub, the post route, the pagination and the structured data, and linked to it from nowhere. The gate caught it in the same commit, before it shipped.

That is the whole argument for these checks. Not that we are careless, but that everybody is careless about exactly the things that are invisible from the page you are looking at.