pdf-quiz-generator/docs/writing-articles.md

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.