From 24724358639bf84e118ef0abbf2388a4ad98d5ec Mon Sep 17 00:00:00 2001 From: Daniel Date: Sat, 12 Sep 2026 19:30:43 +0200 Subject: [PATCH] docs: how article links, highlights and views are actually written The syntax was known only to the code that parses it. This is the author's side of it: `[[264|respiratory failure]]` and why the id form is the one that cannot rot, `==key points==` and the three rules the parser follows, `{{phrase|tip}}`, what each of the three views is for, how to link a question or a whole topic, and what deleting does to a draft versus to something that has been published. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01TqXevQJhxFrM7jJg82cgZN --- docs/README.md | 3 ++ docs/writing-articles.md | 112 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+) create mode 100644 docs/writing-articles.md diff --git a/docs/README.md b/docs/README.md index f3d5afb..0fd15a8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,6 +13,9 @@ Deep technical documentation for the PedsHub pediatric learning platform. | [Deployment](deployment.md) | Docker setup, environment variables, HTTPS, rebuilding, monitoring, troubleshooting, scaling | | [Adaptive sessions](adaptive-sessions.md) | What the Adaptive toggle selects, where the code is, and what it deliberately ignores | | [Study recommendations](study-recommendations.md) | How focus areas are ranked and what readiness means | +| [Writing articles](writing-articles.md) | Cross-reference links, key-point highlights, teaching tips, the three views, linking questions, and what deleting does | +| [Reranking](reranking.md) | Where the cross-encoder is applied and where it deliberately is not | +| [Retrieval thresholds](retrieval-thresholds.md) | The numbers behind sourced / adjacent / open answers | ## Quick Links diff --git a/docs/writing-articles.md b/docs/writing-articles.md new file mode 100644 index 0000000..dc56250 --- /dev/null +++ b/docs/writing-articles.md @@ -0,0 +1,112 @@ +# Writing an article + +Everything in an article body is Markdown, plus four pieces of syntax of our own. +None of them need the editor: they are plain text, so they survive copy-paste, +an AI draft, and a database import equally well. + +## Cross-references — `[[…]]` + +A link from one article to another. Two forms: + +| You write | It renders as | Use when | +|---|---|---| +| `[[264\|respiratory failure]]` | a link labelled *respiratory failure* | **always, by preference** | +| `[[respiratory-failure]]` | a link labelled *respiratory-failure* | quick drafting | + +The first number is the article's **id**, and the id is the part that cannot +change. A slug can be renamed — the old one keeps resolving, because every +former slug is kept in `article_slugs` — but an id is permanent, so the id form +is the one that cannot rot. The label after the bar is whatever reads naturally +in the sentence: *"…severe viral `[[3|bronchiolitis]]`…"* reads as +"…severe viral bronchiolitis…", with the two words linked. + +Where the id comes from: the article's URL. `/articles/264` is id 264. The +editor's Linked-questions panel and the library listing both show it too. + +What happens at the far end: the link opens the article **in a side pane** next +to what you are reading, rather than navigating away — following a reference +does not lose your place. A marker pointing at an article that does not exist is +reported on the editor as a broken link rather than rendering as dead text. + +Inside a **card or a list row** the same marker is flattened to its label +instead of being rendered — a link inside something that is already a link would +swallow the click. + +## Key points — `==…==` + +`Give ==IVIG within 10 days== of fever onset.` — the words between the double +equals are highlighted in yellow, the way a highlighter is run over a textbook. + +Use it in the **high-yield view**, which is what it is for: a summary where +nothing is emphasised is a shorter article, not a revision aid. A few phrases a +section, never a whole paragraph. + +Rules the parser follows, so you can predict it: + +- A highlight may not run across a line break, so one stray `==` cannot swallow + the rest of a section. +- `Sodium == 140` is a lab value, not an unclosed highlight: a lone marker stays + the characters you typed. +- `====` is four equals signs, not an empty highlight. + +The Key button in the editor toolbar wraps the selection for you. + +## Teaching tips — `{{phrase|the tip}}` + +`{{stridor|Inspiratory stridor is extrathoracic until proven otherwise}}` — the +phrase is underlined in the prose, and the sentence appears where the phrase is, +on a click. It is a cross-reference minus the article: sometimes what a learner +needs is one sentence, and writing a whole article to hang it on is how a +sentence goes unwritten. + +The phrase may not contain a bar or a brace; the tip may not contain braces. + +## Maths + +`$…$` inline and `$$…$$` for a display block, rendered by KaTeX. Serum +osmolality set as plain text is a different sentence from the one you wrote. + +## The three views + +Every section belongs to exactly one of them, chosen in the editor's view tabs. +A view with no sections in it is not offered to the reader at all. + +| Variant | What it is for | +|---|---| +| **long** | The full article: pathophysiology, presentation, workup, management. The body of the work, and the default for anything written before views existed. | +| **short** | The high-yield revision view. Tight lists of what a candidate must carry into an exam — not a summary of the long article's structure. This is where `==key points==` belong. | +| **clinical** | What to do at the bedside, when the topic has one. Assessment, immediate management, escalation, disposition. Omit it entirely for a topic that is not acted on clinically. | + +An AI draft is asked for all three (see `ARTICLE_DRAFT_PROMPT`); it is told +explicitly *not* to categorise the article or link it to questions, because both +of those are judgements an educator makes. + +## Linking questions to an article + +From the article editor, under **Linked questions**: + +- **One at a time** — search by the stem, choose whether the link lands on the + whole article or on one section. +- **A whole topic at once** — choose a category, and every question filed under + it (including its subtopics, unless you say otherwise) is linked in one action. + The button carries the number, so you can see that "Cardiology" means 43 + questions before you press it. Up to 300 in one go. + +Either way these are ordinary link rows: removable one at a time, and a +*snapshot* rather than a rule. Questions filed under that category tomorrow are +**not** linked automatically — the alternative would silently attach new +questions to an article nobody has looked at since. + +The same list is editable from each question's own editor, which is the same +relationship seen from the other end. + +## Deleting + +- A draft that was **never published** is deleted outright. There is nothing to + restore, and a trash full of abandoned stubs is a second list to maintain. +- Anything that **has been published**, even once, goes to the **trash** in + Editorial and can be restored exactly as it was. Somewhere there is a + learner's note against one of its sections, a question linked to it, and a + link somebody sent a colleague. + +The confirmation on the editor says which of the two you are about to do.