Four tags let through

Markdown has no way to write a key like Ctrl, m², CO₂, or a line break inside a table cell. The usual answer is a bit of HTML, and that's what blog.panoptikum.social's old posts had. q.e.d. showed it as text instead. Since today, four tags go through (#138, #139), and no others.

Why everything was escaped

A page's text ends up in the built website as it is. If HTML in the text went through, a <script> in a page, or one pasted from somewhere else, would run in every visitor's browser. So options() in crates/qed-core/src/markdown.rs sets comrak's render.escape: any HTML in the text is written as <script>, which shows as text.

Phoenix does the same: a string in a template is escaped unless it's marked with Phoenix.HTML.raw/1. Safe by default, raw only where you say so.

An allowlist, in the tree

The tempting way would be to let all HTML through and remove the bad parts afterwards. That's a blocklist, and blocklists lose: there's always one more attribute (onclick, onerror, style) or a way to write it that nobody thought of. The other way round is an allowlist: name what may pass, escape the rest.

fn allowed_tag(html: &str) -> Option<&'static str> {
    match html.trim().to_ascii_lowercase().as_str() {
        "<br>" | "<br/>" | "<br />" => Some("<br>"),
        "<kbd>" => Some("<kbd>"),
        "</kbd>" => Some("</kbd>"),
        "<sup>" => Some("<sup>"),
        "</sup>" => Some("</sup>"),
        "<sub>" => Some("<sub>"),
        "</sub>" => Some("</sub>"),
        _ => None,
    }
}

Only the exact tag matches, so <kbd class="x"> or <sup onclick=…> stays text. The answer is a &'static str, a text written into the program itself, not the one from the page: what goes into the website is always one of these seven, never the page's own spelling.

Where it's applied matters too. comrak first parses the text into a tree of nodes (NodeValue): paragraphs, text, code, and HtmlInline for a tag in the text. Inline code (`<br>`) is a Code node, not HtmlInline, so a tag written as code is never even looked at, and stays text without any extra rule. Each allowed tag becomes a Raw node, which comrak writes out as it is, even with escaping on:

for node in root.descendants() {
    let tag = match &node.data.borrow().value {
        NodeValue::HtmlInline(html) => allowed_tag(html),
        _ => None,
    };
    if let Some(tag) = tag {
        node.data.borrow_mut().value = NodeValue::Raw(tag.to_string());
    }
}

Borrowed in two steps

Why not change the node right inside the match? Each node's data sits in a RefCell, because comrak's tree is a web of nodes pointing at each other, which Rust's usual one-owner rules can't express. A RefCell checks the borrowing rules while the program runs instead of when it's compiled: many readers (borrow) or one writer (borrow_mut), never both.

node.data.borrow() in the match lives until the end of that statement. Calling borrow_mut() inside it would ask for a writer while a reader is still there, and the program would stop with already borrowed: BorrowMutError. The compiler can't see that; it's a mistake that only shows when the code runs. So the code reads first, keeps the answer (tag, a plain value that borrows nothing), lets the reader go at the semicolon, and only then writes.

Keycaps

<kbd> gets its look in crates/qed-core/assets/site.input.css: a border a little thicker at the bottom, the theme's corner radius and its shaded background, so it fits every theme. On a colored area (a Hero, the footer) it takes that area's text color instead.

Buttons, and icons that came out solid

The text editor is OverType. Its toolbar takes buttons of our own (toolbarButtons in src/lib/MarkdownEditor.svelte), each with an SVG icon, a title and an action that wraps the selection: Key, Superscript, Subscript, Line break, and a Code block next to the code button. They insert with document.execCommand("insertText"), old and officially out of fashion, but it's what OverType's own buttons use, and it's the one way that keeps Ctrl+Z working.

The icons are Lucide's, the set the app uses everywhere: outlines, drawn with fill="none" and a stroke. Two of them, keyboard and square-code, showed up as solid rectangles. OverType's stylesheet has

.overtype-toolbar-button svg { fill: currentColor; }

and in the cascade, fill="none" on an SVG is a presentation attribute: it counts less than any rule in a stylesheet. So the frame was filled and covered what's inside. The icons without a closed shape (superscript, subscript, the arrow) looked right by luck. An inline style="fill: none" counts more than the stylesheet, and the outlines are back.

Light or dark

One more small thing from the same day (#141): q.e.d. now knows which themes are dark, to give them a shaded footer and to show the themes in two groups. theme::is_dark in crates/qed-core/src/theme.rs looks at the page background and asks whether light text reads better on it, with the same contrast formula as the text colors of custom themes. A test then checks the answer against what each of the 39 themes says about itself in the stylesheet (color-scheme: dark). Two ways of asking, one answer.