The README can carry the site link, and one region does it

[dmarx]

Closes #197. Split out of #195, which is now just the record-line bugfix.

Asked from the outside: why is there no link to the site on the README — a missing annotation, the user's job, or something wired halfway?

Third one. The answer was on line 57 of this repository's own README:

<!-- luria:badges -->
…two badges, generated, each linking a report…
<!-- /luria:badges -->

📖 **[dmarx.github.io/luria](https://dmarx.github.io/luria/)** — …

A hand-typed link on the line immediately after the closing marker of a region luria index rewrites on every run. DP-3, one line from its own source, in the repository that ships the principle.

Site.base_url derives from issue_url with no configuration at all, and luria site builds against it — the fact was always there. Nothing wrote it where a reader of the front page would look. Downstream is worse: the anthology has no badge region either (grep -c 'luria:badges' README.md → 0), so it gets neither the counts nor a link, and nothing anywhere says it could. DP-15 exactly — the absence reads like a success.

What this adds

A <!-- luria:site --> region rendered from Site, rewritten by luria index beside the badges and the citation block.

Its own marker, not the badges region. That region's docstring is explicit that it holds "two numbers about the record", and a link is not a number. Separate markers also let a project take one without the other.

A link, not a shields badge. A badge carries a number that moves and the round-trip buys something; a base URL is a constant luria already knows, so an image would cost a reader a request to display text this repository could write itself — which is badges.py's own argument for baking its counts in.

The region holds only the derived fact. Prose about the site stays outside the markers where no rewrite touches it; this README keeps its sentence about backlinks and the graph, and only the link moved inside.

The disclosure opts in; the guard that reports its absence opts out

A region is opt-in and luria never inserts one — the position would have to be guessed, and the guess is wrong for a front page that opens with a logo block, a table or a quote. The badge region's own test already says why: "a tool that edits a README nobody asked it to edit is a tool people stop running."

So a scaffold alone would reach nobody, and luria init writes docs/README.md and no root README, so there is nothing to scaffold markers into anyway. unlinked-site carries it instead: a record that publishes a site its README never names. Satisfied by the URL appearing anywhere in the README, prose link included — the finding is "your front page does not point at the site you publish", never "you must use our marker". That's DP-10 applied twice to one feature.

Scoped by a new [luria.site] publish, defaulting true, and this is the part I'd most like pushed back on. Two predicates were tried first:

• base_url alone — fires for every GitHub project whether or not one is deployed, so a record living only in its repository carries a warning it can never clear.
• "site" in raw — written and tested, and it fails outright: DEFAULTS injects "site" before _site ever sees the user's TOML. That was luck, because the idea was wrong regardless — the defaults' own comment says "the conventional case needs no [luria.site] table at all", so making the table the opt-in would have contradicted the design one function above.

A key nobody sets is a key nobody reads. It earns its place only because the alternative is an unclearable warning. If you'd rather it just fire for every GitHub project, that's a smaller surface and I'll drop the key.

Unplanned, and the better half

Looking for where to put the region found the machinery already written three times — badges.py, citation.py, and about to be a fourth here. Four lines each (OPEN, CLOSE, a compiled regex, a sub), and they had already drifted in spelling: re.DOTALL in one, re.S in the other; an f-string against concatenation.

Now one implementation in readme.py — markers, has, rewrite, path — with both callers keeping their OPEN/CLOSE names so nothing addressing them had to move. Splitting region() into _inner() plus markers was the whole mechanical cost. Nobody extracts at two copies; reaching for a fourth is the signal.

Fired before trusting

Reports the anthology, which is the record that prompted the question:

README.md never names dmarx.github.io/anthology-of-the-sota, where `luria site`
publishes this record — add a `<!-- luria:site -->` / `<!-- /luria:site -->`
region for `luria index` to fill, or write the link yourself

…and is silent here, now that the region writes what the deleted hand-typed line used to say. A test asserts this repository's own README names its site, so the real corpus is covered and not only the fixtures.

Checks

python -m pytest tests -q → 919 passed on this branch alone. luria link --fix, luria index, luria lint → clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YP4P3m8rzVFb8idnTE4FfT

---

Generated by Claude Code