Docs README structure & cross-linking

README structure & cross-linking

A project's README travels far beyond the site — GitHub, npm, plugin registries, mirrors — where the site chrome doesn't exist, so it must carry the mesh links in its own text — a docs link near the top, a grouped "Get it" section, and a fairyfox.io footer near the bottom.

A project’s README is the most-travelled document it owns, and out on GitHub, npm, or a plugin registry it has none of the site chrome — no header, no navigation, no footer tying it back to the mesh. So the README has to carry those links itself. The canonical machine copy of this standard, with the copy-paste block, is in the repository at hub/standards/readme.md.

The rule

Three worded link placements are required, around whatever content the README already has: a documentation link near the top (pointing at the project’s page on the shared domain), a grouped “Get it” section gathering every place the project is used, downloaded, or published — the live app, releases, and each store or registry it ships to, labelled and organized rather than dumped as raw URLs — and a fairyfox.io footer near the bottom that links back to the hub and states the project is part of the Fairy Fox mesh.

Badges front the top of every README already, but a badge is an image: easy to skim past, and invisible in plain-text views and some registries. A worded, labelled link survives where a badge doesn’t, and it’s the thing a reader actually follows. The two are complementary — the badge is a glanceable signal, the link is the door. The docs link and the mesh footer apply to every project without exception; a store or deploy link is present whenever that destination exists, and omitting one that does exist takes a recorded exception rather than a silent drop. Complements README badges and the on-site docs-site chrome.