Links and cards: the editorial rules¶
The rules the bank is written to, set by the user. They are here because the code enforces some of them and cannot enforce the rest, and the half a person does is the half that decides whether the library reads well.
"It will never be perfect but we will try."
Cross-references between articles¶
Link only where the link takes the reader somewhere useful. A link is an offer to leave the page; it has to be worth taking.
An article may link its own subject. This was briefly excluded — in Adolescent Depression, "depression" would not link — on a reading of the rule that went too far. The user overruled it: "I told you you have been doing it right." A link the owner does not want is one to remove; an absence is one they have to notice. The 286 links that exclusion removed were restored from the snapshots taken before it ran.
Keywords that point to articles get linked, and it will keep getting denser. The automatic pass links the first mention of each article per section, up to six. A link here is a hover or a click — it does not open anything as you read past it — so it does not interrupt and does not need rationing. What stays capped is one link per target per section, so the same word is never linked twice.
Never inside a table row. The marker is [[Label|slug]] and a markdown
cell ends at a pipe, so a link written into a row splits the cell: the table
gains a column and the marker reaches the reader in halves. Both marker forms
are affected, including [[288|Label]] written by hand. If a cell needs a
cross-reference, put it in the sentence under the table.
Drug names link to a drug database when there is one. There is not one yet, so they stay plain.
Guideline and tool names — GLAD-PC, PECARN, PHQ-A — link to their article where we have one.
How it runs¶
article_service.link_cross_references() runs on publish and on saving a
published article. Drafts are left alone: they are still being written, and
links appearing under the writer's cursor are not a kindness.
It is idempotent. autolink.apply() seeds its seen-set from the markers
already in the text, so a second run adds only mentions that were not linked
before. This was once false — the seen-set started empty, so each run linked
the next mention of a word already linked, and 249 duplicates accumulated
across 99 articles before it was caught. Publishing twice is now a no-op, and
a test holds that.
Cards and the pop-up glossary¶
A card is a click's worth of context: a short explanation, or a fun fact. Anything longer is a topic — an article, with a link to it — not a card. The glossary enforces 400 characters, which is about four sentences and is where an explanation stops being an aside and starts being an article nobody has written yet.
Written as {{term}} in any article, stem, explanation or option. The
definition comes from the shared table at render time, so a term used in forty
articles is written once and corrected once. Four kinds — define, fact,
why, caution — each with its own mark and colour. {{phrase|explanation}}
writes one inline instead, and {{|explanation|kind}} draws a chip at the end
of a sentence for an aside that is not about any one word.
Load them with POST /glossary/bulk, up to 200 at a time, upserting on the
term folded to lower case. A term nobody has defined yet reads as plain prose,
so entries and the prose that references them can land in either order.
Decks¶
A deck is the unit, never the card. An article shows related decks, not a list of every card tied to it — listing cards turns the foot of a reading page into a dump of fronts and backs, and gives away the answers besides. The same holds for how questions relate to cards.
Decks relate through the shared category: a generated deck inherits the article's category, and a manual deck must be given one. A deck with no category relates to nothing and appears nowhere.