Every page links the family the first time it says the name

A marketing site is a set of pages that all describe parts of one thing, and almost none of them link to each other. Not through neglect: linking by hand is tedious, it goes stale the moment a page is renamed, and it is the first thing dropped when a page is written in a hurry. The result is a site where a reader who wants the page you just mentioned has to go back to a search engine to find it.

Six Rutba sites had that problem at once. So the prose on them is structured content now — sentences held as data rather than as markup inside a page component — and one pass over that data links the family’s pages where a page first mentions them.

A dictionary, not a search-and-replace

The linker works from a dictionary: the pages across the family, and the words that mean each one. That is more than a list of titles. “The Relay”, “Rutba Relay” and “social publishing” can all mean the same page; “Books” means the accounting product in a sentence about the ledger and means nothing in a sentence about a library.

Three rules keep it from turning a page into a sea of blue:

• First mention only. The second time a paragraph says the name, it stays a word. A reader who did not click the first one is not going to click the fourth.
• A budget per page. Past a handful of links, prose stops reading like prose, so a page gets a budget and the linker spends it on the earliest mentions.
• Never a link to the page you are on. A page that links to itself is a page that has stopped paying attention.

And one rule about scope, which took a bug to find: a word that names a page only on one site is not a subject anywhere else. Sign’s own vocabulary links within sign.rutba.io; it does not turn every appearance of an ordinary word elsewhere into a link to a page that reader has no reason to want.

Which words, and which parts of a page

It runs over running prose: paragraphs, list items, the body of a callout. Never a heading, which is a label rather than a sentence, and which the contents list repeats. Never a quotation, which is somebody’s words and not ours to edit. Never a table cell, where a link in every row of a comparison is noise rather than help. Never a call to action, which already has the one link it exists for.

On the blog it does the same job to a post’s blocks before they render, so a link the dictionary adds is drawn exactly like one an author typed and nothing about the page has to know the difference. It also tells the page which products a post is really about — useful for choosing what to offer at the foot of it, which is how a reader ends up somewhere better than the back button.

Why the prose had to become data first

None of this is possible while a page’s words live inside its markup. Converted to structured content, the same sentences can be linked, counted, checked for claims we no longer make, and — the reason that matters most here — kept identical when a page is rebuilt. The conversion was done page by page, word for word, so that nothing was rewritten in the move: relay.rutba.io, sign.rutba.io, office.rutba.io, the partner programme’s pages and the halves of rutba.io that are ours.

The payoff is small per page and large across a family: a reader who meets a product in a sentence can open it, every time, on every site, without anybody having remembered to type a link.