documents: Markdown containers are the elements GitHub writes, repaired with tags as HTML5 repairs; shortcodes read from decoded text, kept in autolinks and <code>

A raw end tag ends the Markdown element of its name; an end tag pops every
element above its target and only formatting elements reopen, so mark, kbd
and del stop where the browser stops them; a new anchor ends the open one.
Emoji read after escapes and references, as GitHub's Markdown API shows.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -13,7 +13,7 @@ Ely GPUI Component. A component library for GPUI, in light and dark.
 - Web views: `wry` 0.57 (Apache-2.0 OR MIT, default features off, macOS only) lays a child WKWebView over the window.
 - Terminal: `alacritty_terminal` 0.26 (Apache-2.0, default features off, native only) for the grid, its parser and the pseudo-terminal; `futures` carries its events. `vte` 0.15 (Apache-2.0 OR MIT), the parser it re-exports, reads `AnsiText`'s codes alone, so colored output builds for wasm32.
 - Diffs: `similar` 3.2 (Apache-2.0) for line and word diffs and three-way merges; its `unicode` feature splits words at punctuation.
-- Markdown: `markdown` 1.0.0 (markdown-rs, MIT) reads GitHub's flavor and math into a syntax tree with byte positions for `MarkdownRenderer`, `MarkdownEditor`, the highlights, block ranges and outline. `MarkdownRenderer` draws display math through `typography::Latex`, a ```` ```mermaid ```` block through `documents::Diagram`, and pictures from the owner's folder (`base`) or `data:` addresses (`base64` 0.22, MIT OR Apache-2.0); web pictures stay unloaded. Inline math shows as TeX: gpui text carries no inline pictures. `MarkdownDocument` holds a whole file in one `CodeEditor` (text and undo, colored by `CodeEditor::highlighter` with `markdown_highlights`): visual draws the file's top-level blocks in a gpui `list`, a pressed block opening as its source in a `TextInput` whose typing is the document's text at once and whose write-back is one undo step; source is the editor; preview draws without presses. A written-back block, a mode switch or a new text is read at once up to 128 KiB, longer ones on the background executor; typing in source or split reads 300 ms after the last key, off the main thread (markdown-rs grows with the square of a paragraph's lines: 40,000 lines take 0.9 s). Texts past `LARGEST_READ` (2 MiB) are never read: no blocks, no outline. A new read keeps the list's blocks alike at both ends. One caret serves every mode: the editor's selection, which a written-back block moves; `set_caret` and `set_top_line` set caret and view apart; a top line asked (numbered, so a late frame callback finishes only its own ask; new text places it again, clamped to the text as it then is) waits for the read, lands on its block, then a frame later at its share of the block's height; `reveal` is such an ask with the caret at its line; a switch between source and the list keeps the top line, one between visual and preview keeps the list's scroll as it is. A block opens only when the read is of the text as it is now. A pressed block keeps its identity across the write-back of the one before it. Blocks are Tab stops that Enter or Space opens; preview takes no presses, undo or redo. `CodeEditor` keeps at most 64 MiB of undo and redo text, dropping the oldest undo and then the farthest redo after every record, composition, undo and redo. `BlockData::from_markdown` and its export still read with `pulldown-cmark` 0.13 (MIT, default features off); it adds GitHub's alerts, a callout's form, and reads each field's inline Markdown from the source by offset, as written.
+- Markdown: `markdown` 1.0.0 (markdown-rs, MIT) reads GitHub's flavor and math into a syntax tree with byte positions for `MarkdownRenderer`, `MarkdownEditor`, the highlights, block ranges and outline. `MarkdownRenderer` draws display math through `typography::Latex`, a ```` ```mermaid ```` block through `documents::Diagram`, and pictures from the owner's folder (`base`) or `data:` addresses (`base64` 0.22, MIT OR Apache-2.0); web pictures stay unloaded. Inline math shows as TeX: gpui text carries no inline pictures. Inline it reads as Typora's defaults: `:shortcode:` turns to its emoji as GitHub reads it (the `emojis` crate's names, GitHub's today, so `:cricket:` is the insect; read after escapes and references, so `\:smile:` turns too; inside an autolink or `<code>` it stays text), inline HTML's `u`, `b`/`strong`, `i`/`em`, `s`/`del`/`strike`, `code`/`kbd`, `mark`, `br` and `a href` draw as what they mean and other tags, hyphenated names too, vanish, leaving their text; attribute values split on ASCII whitespace alone and decode as HTML decodes them; each Markdown container is the element GitHub writes (`em`, `strong`, `del`, `a`), on one stack with the tags and repaired as HTML5 repairs: an end tag closes the innermost element of its name and all above it, of which only formatting elements (`a`, `b`, `code`, `em`, `i`, `s`, `strike`, `strong`, `u`) reopen, a new `a` ends the open one and an `a` without `href` links nothing; other tags are not tracked, and `</br>` breaks as `<br>` does; and a footnote reference is its number in superscript, numbered by first reference, as its definition is; one `~` still strikes. `MarkdownDocument` holds a whole file in one `CodeEditor` (text and undo, colored by `CodeEditor::highlighter` with `markdown_highlights`): visual draws the file's top-level blocks in a gpui `list`, a pressed block opening as its source in a `TextInput` whose typing is the document's text at once and whose write-back is one undo step; source is the editor; preview draws without presses. A written-back block, a mode switch or a new text is read at once up to 128 KiB, longer ones on the background executor; typing in source or split reads 300 ms after the last key, off the main thread (markdown-rs grows with the square of a paragraph's lines: 40,000 lines take 0.9 s). Texts past `LARGEST_READ` (2 MiB) are never read: no blocks, no outline. A new read keeps the list's blocks alike at both ends. One caret serves every mode: the editor's selection, which a written-back block moves; `set_caret` and `set_top_line` set caret and view apart; a top line asked (numbered, so a late frame callback finishes only its own ask; new text places it again, clamped to the text as it then is) waits for the read, lands on its block, then a frame later at its share of the block's height; `reveal` is such an ask with the caret at its line; a switch between source and the list keeps the top line, one between visual and preview keeps the list's scroll as it is. A block opens only when the read is of the text as it is now. A pressed block keeps its identity across the write-back of the one before it. Blocks are Tab stops that Enter or Space opens; preview takes no presses, undo or redo. `CodeEditor` keeps at most 64 MiB of undo and redo text, dropping the oldest undo and then the farthest redo after every record, composition, undo and redo. `BlockData::from_markdown` and its export still read with `pulldown-cmark` 0.13 (MIT, default features off); it adds GitHub's alerts, a callout's form, and reads each field's inline Markdown from the source by offset, as written.
 - Pictures: `image` 0.25 (MIT OR Apache-2.0), the crate gpui decodes with, default features off; it turns decoded frames and rims map tiles.
 - Math and diagrams: RaTeX 0.1.14 (`ratex-parser`, `ratex-layout`, `ratex-svg` with `embed-fonts`, `ratex-types`; MIT, KaTeX's fonts OFL) typesets `Latex` to SVG with outlined glyphs; `mermaid-rs-renderer` 0.3.1 (MIT, default features off) draws `Diagram`. Both go through gpui's `SvgRenderer` at the window's scale, loaded as gpui assets off the main thread; `usvg` 0.46, gpui's own, reads a diagram's size. A RaTeX or Mermaid panic on parsed input becomes the element's error. Each element holds its picture through `primitives::held`: a new source, or the element leaving the window, removes the old asset from gpui's cache and drops its image from the atlas after the frame.
 - Maps: Natural Earth's 110m countries (public domain). `assets/maps/countries.geojson`, trimmed by `scripts/countries.py` to an ISO code, a name and positions to 0.01°, backs `maps::WorldMap`; the gallery's tiles are cut from the same file, z0 to z3, by `scripts/tiles.py` with Pillow.

src/documents/render.rs

@@ -149,6 +149,18 @@ impl Draw<'_> {
                         color: Some(colors.fg_subtle),
                         ..HighlightStyle::default()
                     },
+                    Style::Underline => HighlightStyle {
+                        underline: Some(UnderlineStyle {
+                            thickness: rule,
+                            color: None,
+                            wavy: false,
+                        }),
+                        ..HighlightStyle::default()
+                    },
+                    Style::Mark => HighlightStyle {
+                        background_color: Some(colors.warning_subtle),
+                        ..HighlightStyle::default()
+                    },
                 };
                 (range.clone(), highlight)
             })

src/documents/tree/html.rs

@@ -0,0 +1,321 @@
+use markdown::decode_named;
+
+use super::Style;
+
+/// One HTML tag as written: its lowercase name and attributes.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct Tag {
+    pub name: String,
+    pub closing: bool,
+    pub attributes: Vec<(String, String)>,
+}
+
+impl Tag {
+    pub fn attribute(&self, name: &str) -> Option<&str> {
+        self.attributes
+            .iter()
+            .find(|(key, _)| key == name)
+            .map(|(_, value)| value.as_str())
+    }
+}
+
+/// How Typora shows an inline tag; others show text.
+pub(crate) fn inline_style(name: &str) -> Option<Style> {
+    match name {
+        "u" => Some(Style::Underline),
+        "b" | "strong" => Some(Style::Strong),
+        "i" | "em" => Some(Style::Emphasis),
+        "s" | "del" | "strike" => Some(Style::Strike),
+        "code" | "kbd" => Some(Style::Code),
+        "mark" => Some(Style::Mark),
+        "a" => Some(Style::Link),
+        _ => None,
+    }
+}
+
+/// HTML5's formatting elements reopen past a crossed close.
+pub(crate) fn reopens(name: &str) -> bool {
+    matches!(
+        name,
+        "a" | "b" | "code" | "em" | "i" | "s" | "strike" | "strong" | "u"
+    )
+}
+
+/// `html` as one tag; comments and the rest are none.
+pub(crate) fn tag(html: &str) -> Option<Tag> {
+    let inner = html.trim().strip_prefix('<')?.strip_suffix('>')?;
+    let (closing, inner) = match inner.strip_prefix('/') {
+        Some(rest) => (true, rest),
+        None => (false, inner),
+    };
+    if !inner.starts_with(|ch: char| ch.is_ascii_alphabetic()) {
+        return None;
+    }
+    let named = inner
+        .find(|ch: char| !(ch.is_ascii_alphanumeric() || ch == '-'))
+        .unwrap_or(inner.len());
+    Some(Tag {
+        name: inner[..named].to_ascii_lowercase(),
+        closing,
+        attributes: attributes(&inner[named..]),
+    })
+}
+
+/// `name="value"`, `name='value'`, `name=value` and bare names.
+fn attributes(mut rest: &str) -> Vec<(String, String)> {
+    let mut out = Vec::new();
+    loop {
+        rest = rest.trim_start_matches(spacing);
+        // A slash between attributes closes the tag itself.
+        if let Some(after) = rest.strip_prefix('/') {
+            rest = after;
+            continue;
+        }
+        let named = rest
+            .find(|ch: char| spacing(ch) || ch == '=' || ch == '/')
+            .unwrap_or(rest.len());
+        if named == 0 {
+            return out;
+        }
+        let name = rest[..named].to_ascii_lowercase();
+        rest = rest[named..].trim_start_matches(spacing);
+        let Some(after) = rest.strip_prefix('=') else {
+            out.push((name, String::new()));
+            continue;
+        };
+        let after = after.trim_start_matches(spacing);
+        let (value, left) = match after.chars().next() {
+            Some(quote @ ('"' | '\'')) => match after[1..].find(quote) {
+                Some(end) => (&after[1..1 + end], &after[2 + end..]),
+                None => (&after[1..], ""),
+            },
+            _ => {
+                let end = after.find(spacing).unwrap_or(after.len());
+                (&after[..end], &after[end..])
+            }
+        };
+        out.push((name, decoded(value)));
+        rest = left;
+    }
+}
+
+/// HTML's whitespace, which is ASCII alone.
+fn spacing(ch: char) -> bool {
+    matches!(ch, ' ' | '\t' | '\n' | '\r' | '\x0C')
+}
+
+/// An attribute value with references decoded as HTML does.
+fn decoded(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut rest = text;
+    while let Some(at) = rest.find('&') {
+        out.push_str(&rest[..at]);
+        rest = &rest[at..];
+        match attribute_reference(rest) {
+            Some((value, len)) => {
+                out.push_str(&value);
+                rest = &rest[len..];
+            }
+            None => {
+                out.push('&');
+                rest = &rest[1..];
+            }
+        }
+    }
+    out.push_str(rest);
+    out
+}
+
+/// Longest reference name HTML knows, in bytes.
+const LONGEST: usize = 32;
+
+/// A reference at `text`'s start, as HTML reads values.
+fn attribute_reference(text: &str) -> Option<(String, usize)> {
+    let body = text.strip_prefix('&')?;
+    if let Some(number) = body.strip_prefix('#') {
+        let (digits, radix) = match number.strip_prefix(['x', 'X']) {
+            Some(hex) => (hex, 16),
+            None => (number, 10),
+        };
+        let len = digits
+            .find(|ch: char| !ch.is_digit(radix))
+            .unwrap_or(digits.len());
+        if len == 0 {
+            return None;
+        }
+        let code = digits[..len].chars().try_fold(0u32, |code, ch| {
+            code.checked_mul(radix)?.checked_add(ch.to_digit(radix)?)
+        });
+        let ended = usize::from(digits[len..].starts_with(';'));
+        let used = 2 + (number.len() - digits.len()) + len + ended;
+        return Some((numeric(code).to_string(), used));
+    }
+    let len = body
+        .find(|ch: char| !ch.is_ascii_alphanumeric())
+        .unwrap_or(body.len());
+    let name = &body[..len];
+    if (1..=LONGEST).contains(&len)
+        && body[len..].starts_with(';')
+        && let Some(value) = decode_named(name, true)
+    {
+        return Some((value, len + 2));
+    }
+    let bare = !body[len..].starts_with(['=', ';']);
+    (bare && legacy(name)).then(|| (decode_named(name, true).expect("a legacy name"), len + 1))
+}
+
+/// A name HTML decodes without its semicolon.
+fn legacy(name: &str) -> bool {
+    if matches!(name, "AMP" | "LT" | "GT" | "QUOT" | "COPY" | "REG") {
+        return true;
+    }
+    decode_named(name, false).is_some_and(|value| {
+        let mut chars = value.chars();
+        let one = chars.next().filter(|_| chars.next().is_none());
+        one.is_some_and(|ch| matches!(ch, '&' | '<' | '>' | '"' | '\u{A0}'..='\u{FF}'))
+    })
+}
+
+/// The character a numeric reference names, as HTML maps it.
+fn numeric(code: Option<u32>) -> char {
+    // Windows-1252 for the C1 block, as browsers do.
+    const C1: [u32; 32] = [
+        0x20AC, 0x81, 0x201A, 0x0192, 0x201E, 0x2026, 0x2020, 0x2021, 0x02C6, 0x2030, 0x0160,
+        0x2039, 0x0152, 0x8D, 0x017D, 0x8F, 0x90, 0x2018, 0x2019, 0x201C, 0x201D, 0x2022, 0x2013,
+        0x2014, 0x02DC, 0x2122, 0x0161, 0x203A, 0x0153, 0x9D, 0x017E, 0x0178,
+    ];
+    match code {
+        Some(code @ 0x80..=0x9F) => char::from_u32(C1[(code - 0x80) as usize]),
+        Some(0) | None => None,
+        Some(code) => char::from_u32(code),
+    }
+    .unwrap_or(char::REPLACEMENT_CHARACTER)
+}
+
+/// `text` with each known `:shortcode:` as its emoji.
+pub(crate) fn emoji(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut rest = text;
+    while let Some(at) = rest.find(':') {
+        out.push_str(&rest[..at]);
+        let after = &rest[at + 1..];
+        let len = after
+            .find(|ch: char| !shortcode_char(ch))
+            .unwrap_or(after.len());
+        let found = after[len..]
+            .starts_with(':')
+            .then(|| emojis::get_by_shortcode(&after[..len]))
+            .flatten();
+        match found {
+            Some(found) => {
+                out.push_str(found.as_str());
+                rest = &after[len + 1..];
+            }
+            None => {
+                out.push(':');
+                rest = after;
+            }
+        }
+    }
+    out.push_str(rest);
+    out
+}
+
+fn shortcode_char(ch: char) -> bool {
+    ch.is_ascii_alphanumeric() || matches!(ch, '_' | '+' | '-')
+}
+
+/// `n` in superscript digits.
+pub(crate) fn superscript(n: usize) -> String {
+    const DIGITS: [char; 10] = ['⁰', '¹', '²', '³', '⁴', '⁵', '⁶', '⁷', '⁸', '⁹'];
+    n.to_string()
+        .bytes()
+        .map(|digit| DIGITS[usize::from(digit - b'0')])
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_tag_reads_its_name_and_attributes() {
+        let link = tag("<A HREF=\"https://ely.dev\" title='x' hidden>").expect("a tag");
+        assert_eq!((link.name.as_str(), link.closing), ("a", false));
+        assert_eq!(link.attribute("href"), Some("https://ely.dev"));
+        assert_eq!(link.attribute("title"), Some("x"));
+        assert_eq!(link.attribute("hidden"), Some(""));
+        assert_eq!(
+            tag("</u>").map(|t| (t.name, t.closing)),
+            Some(("u".into(), true))
+        );
+        assert_eq!(tag("<br/>").map(|t| t.name), Some("br".into()));
+        assert_eq!(tag("<u-box>").map(|t| t.name), Some("u-box".into()));
+        assert_eq!(tag("<!-- note -->"), None);
+        assert_eq!(tag("<1>"), None);
+    }
+
+    #[test]
+    fn attribute_values_keep_slashes_and_decode_references() {
+        let bare = tag("<a href=/path/>").expect("a tag");
+        assert_eq!(bare.attribute("href"), Some("/path/"));
+        let closed = tag("<img src=\"a.png\" />").expect("a tag");
+        assert_eq!(closed.attribute("src"), Some("a.png"));
+        let query = tag("<a href=\"https://x.test/?q=1&amp;p=2&#38;r=&#x33;&nope;\">");
+        let query = query.expect("a tag");
+        assert_eq!(
+            query.attribute("href"),
+            Some("https://x.test/?q=1&p=2&r=3&nope;")
+        );
+    }
+
+    #[test]
+    fn values_decode_as_a_browser_decodes_them() {
+        let href = |html: &str| {
+            tag(html)
+                .expect("a tag")
+                .attribute("href")
+                .map(str::to_owned)
+        };
+        let cases = [
+            ("<a href=\"?q=1&#38page=2\">", "?q=1&page=2"),
+            ("<a href=\"/&#128;&#x9F;&#129;\">", "/€Ÿ\u{81}"),
+            (
+                "<a href=\"&#0;&#x110000;&#xD800;\">",
+                "\u{FFFD}\u{FFFD}\u{FFFD}",
+            ),
+            (
+                "<a href=\"&amp page&ampx&amp=&notin;&AMP\">",
+                "& page&ampx&amp=∉&",
+            ),
+            ("<a href=/a\u{A0}b>", "/a\u{A0}b"),
+        ];
+        for (html, want) in cases {
+            assert_eq!(href(html).as_deref(), Some(want), "{html}");
+        }
+    }
+
+    #[test]
+    fn long_runs_scan_in_linear_time() {
+        let (amps, colons) = ("&".repeat(1 << 18), ":zq".repeat(1 << 16));
+        let started = web_time::Instant::now();
+        assert_eq!(decoded(&amps).len(), amps.len());
+        assert_eq!(emoji(&colons).len(), colons.len());
+        let spent = started.elapsed();
+        assert!(spent.as_secs() < 2, "256 KiB took {spent:?}");
+    }
+
+    #[test]
+    fn known_shortcodes_become_emoji() {
+        assert_eq!(emoji("hi :smile: :+1:"), "hi 😄 👍");
+        assert_eq!(emoji(":nope: at 10:30 and ::"), ":nope: at 10:30 and ::");
+        assert_eq!(emoji("a:smile:b :x:smile:"), "a😄b ❌smile:");
+        assert_eq!(emoji("é :smile: 中"), "é 😄 中");
+    }
+
+    #[test]
+    fn numbers_go_up() {
+        assert_eq!(superscript(1), "¹");
+        assert_eq!(superscript(120), "¹²⁰");
+    }
+}

src/documents/tree/mod.rs

@@ -4,6 +4,8 @@ use markdown::mdast::{self, AlignKind};
 
 use super::markdown::{span, tree, walk};
 
+mod html;
+
 /// How a stretch of inline text prints.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum Style {
@@ -14,6 +16,9 @@ pub enum Style {
     Link,
     Math,
     Footnote,
+    Underline,
+    /// A highlighted run, as `<mark>`.
+    Mark,
 }
 
 /// Inline text, its styled stretches and link addresses.
@@ -63,13 +68,25 @@ pub enum Node {
 pub(crate) struct Reader<'a> {
     source: &'a str,
     urls: HashMap<String, String>,
+    /// Footnotes numbered by their first reference.
+    notes: HashMap<String, usize>,
+}
+
+/// An open element, as HTML names it.
+struct Opened {
+    name: String,
+    start: usize,
+    style: Option<Style>,
+    url: Option<String>,
 }
 
 /// Inline text being built, and the containers open around it.
 #[derive(Default)]
 struct Run {
     text: Inline,
-    open: Vec<(usize, Style, Option<String>)>,
+    open: Vec<Opened>,
+    /// Inside an autolink: its text stays as written.
+    verbatim: bool,
 }
 
 impl Run {
@@ -77,21 +94,84 @@ impl Run {
     fn cut(&mut self) -> Inline {
         let mut done = std::mem::take(&mut self.text);
         let end = done.text.len();
-        for (start, style, url) in self.open.iter_mut().rev() {
-            if *start < end {
-                done.styles.push((*start..end, *style));
-                if let Some(url) = url {
-                    done.links.push((*start..end, url.clone()));
-                }
-            }
-            *start = 0;
+        for opened in self.open.iter_mut().rev() {
+            close(&mut done, opened, end);
+            opened.start = 0;
         }
         done
     }
 
     /// The innermost open link's address.
     fn link(&self) -> Option<String> {
-        self.open.iter().rev().find_map(|(_, _, url)| url.clone())
+        self.open.iter().rev().find_map(|opened| opened.url.clone())
+    }
+
+    /// Opens or closes an element for an inline HTML tag.
+    fn html(&mut self, written: &str) {
+        let Some(tag) = html::tag(written) else {
+            return;
+        };
+        if tag.name == "br" {
+            return self.text.text.push('\n');
+        }
+        let Some(style) = html::inline_style(&tag.name) else {
+            return;
+        };
+        if tag.closing {
+            return self.end(&tag.name);
+        }
+        let url = match style {
+            Style::Link => tag.attribute("href").map(str::to_string),
+            _ => None,
+        };
+        let style = (style != Style::Link || url.is_some()).then_some(style);
+        self.start(&tag.name, style, url);
+    }
+
+    /// Opens `name`; a new `a` ends the open one.
+    fn start(&mut self, name: &str, style: Option<Style>, url: Option<String>) {
+        if name == "a" {
+            self.end("a");
+        }
+        self.open.push(Opened {
+            name: name.to_string(),
+            start: self.text.text.len(),
+            style,
+            url,
+        });
+    }
+
+    /// Ends the innermost `name`, as HTML5 repairs nesting.
+    fn end(&mut self, name: &str) {
+        let Some(at) = self.open.iter().rposition(|opened| opened.name == name) else {
+            return;
+        };
+        let end = self.text.text.len();
+        let above = self.open.split_off(at + 1);
+        let ended = self.open.pop().expect("found at `at`");
+        close(&mut self.text, &ended, end);
+        for opened in above {
+            close(&mut self.text, &opened, end);
+            if html::reopens(&opened.name) {
+                self.open.push(Opened {
+                    start: end,
+                    ..opened
+                });
+            }
+        }
+    }
+}
+
+/// Records `opened` as styled up to `end`.
+fn close(text: &mut Inline, opened: &Opened, end: usize) {
+    if opened.start >= end {
+        return;
+    }
+    if let Some(style) = opened.style {
+        text.styles.push((opened.start..end, style));
+    }
+    if let Some(url) = &opened.url {
+        text.links.push((opened.start..end, url.clone()));
     }
 }
 
@@ -111,14 +191,25 @@ impl<'a> Reader<'a> {
     pub(crate) fn new(source: &'a str, root: &mdast::Node) -> Self {
         let mut nodes = Vec::new();
         walk(root, &mut nodes);
-        let mut urls = HashMap::new();
+        let (mut urls, mut notes) = (HashMap::new(), HashMap::new());
         for node in nodes {
-            if let mdast::Node::Definition(definition) = node {
-                urls.entry(definition.identifier.clone())
-                    .or_insert_with(|| definition.url.clone());
+            match node {
+                mdast::Node::Definition(definition) => {
+                    urls.entry(definition.identifier.clone())
+                        .or_insert_with(|| definition.url.clone());
+                }
+                mdast::Node::FootnoteReference(note) => {
+                    let next = notes.len() + 1;
+                    notes.entry(note.identifier.clone()).or_insert(next);
+                }
+                _ => {}
             }
         }
-        Self { source, urls }
+        Self {
+            source,
+            urls,
+            notes,
+        }
     }
 
     fn blocks(&self, nodes: &[mdast::Node], out: &mut Vec<Node>) {
@@ -193,10 +284,13 @@ impl<'a> Reader<'a> {
             }
             mdast::Node::ThematicBreak(_) => out.push(Node::Rule),
             mdast::Node::FootnoteDefinition(note) => out.push(Node::Footnote {
-                label: note
-                    .label
-                    .clone()
-                    .unwrap_or_else(|| note.identifier.clone()),
+                label: match self.notes.get(&note.identifier) {
+                    Some(number) => number.to_string(),
+                    None => note
+                        .label
+                        .clone()
+                        .unwrap_or_else(|| note.identifier.clone()),
+                },
                 body: self.nested(&note.children),
             }),
             mdast::Node::Html(_) | mdast::Node::Definition(_) => {}
@@ -229,17 +323,22 @@ impl<'a> Reader<'a> {
 
     fn inline_into(&self, node: &mdast::Node, run: &mut Run, images: &mut Images) {
         let text = &mut run.text;
-        let (children, style, url) = match node {
+        let (children, (name, style), url) = match node {
             mdast::Node::Text(words) => {
-                let soft = words.value.replace("\r\n", " ").replace(['\r', '\n'], " ");
-                return text.text.push_str(&soft);
+                let code = run.open.iter().any(|opened| opened.name == "code");
+                let shown = match run.verbatim || code {
+                    true => words.value.clone(),
+                    false => html::emoji(&words.value),
+                };
+                let soft = shown.replace("\r\n", " ").replace(['\r', '\n'], " ");
+                return run.text.text.push_str(&soft);
             }
             mdast::Node::Break(_) => return text.text.push('\n'),
             mdast::Node::InlineCode(code) => return styled(text, &code.value, Style::Code),
             mdast::Node::InlineMath(math) => return styled(text, &math.value, Style::Math),
             mdast::Node::FootnoteReference(note) => {
-                let label = note.label.as_ref().unwrap_or(&note.identifier);
-                return styled(text, &format!("[{label}]"), Style::Footnote);
+                let number = self.notes[&note.identifier];
+                return styled(text, &html::superscript(number), Style::Footnote);
             }
             mdast::Node::Image(_) | mdast::Node::ImageReference(_) => {
                 let (alt, url) = match node {
@@ -259,30 +358,29 @@ impl<'a> Reader<'a> {
                     Images::After(out) => out.push(Node::Image { alt, url, link }),
                 };
             }
-            mdast::Node::Html(_) => return,
-            mdast::Node::Strong(strong) => (&strong.children, Style::Strong, None),
-            mdast::Node::Emphasis(emphasis) => (&emphasis.children, Style::Emphasis, None),
-            mdast::Node::Delete(delete) => (&delete.children, Style::Strike, None),
-            mdast::Node::Link(link) => (&link.children, Style::Link, Some(link.url.clone())),
+            mdast::Node::Html(written) => return run.html(&written.value),
+            mdast::Node::Strong(strong) => (&strong.children, ("strong", Style::Strong), None),
+            mdast::Node::Emphasis(emphasis) => (&emphasis.children, ("em", Style::Emphasis), None),
+            mdast::Node::Delete(delete) => (&delete.children, ("del", Style::Strike), None),
+            mdast::Node::Link(link) => (&link.children, ("a", Style::Link), Some(link.url.clone())),
             mdast::Node::LinkReference(link) => (
                 &link.children,
-                Style::Link,
+                ("a", Style::Link),
                 Some(self.url(&link.identifier)),
             ),
             other => unreachable!("{other:?} is no inline outside MDX"),
         };
-        run.open.push((run.text.text.len(), style, url));
+        // A container is the element GitHub writes.
+        run.start(name, Some(style), url);
+        let autolink =
+            matches!(node, mdast::Node::Link(_)) && !self.source[span(node)].starts_with('[');
+        let outer = run.verbatim;
+        run.verbatim |= autolink;
         for child in children {
             self.inline_into(child, run, images);
         }
-        let (start, style, url) = run.open.pop().expect("the container opened above");
-        let end = run.text.text.len();
-        if start < end {
-            run.text.styles.push((start..end, style));
-            if let Some(url) = url {
-                run.text.links.push((start..end, url));
-            }
-        }
+        run.verbatim = outer;
+        run.end(name);
     }
 }
 

src/documents/tree/tests.rs

@@ -189,7 +189,176 @@ fn footnotes_number_their_references_and_hold_their_body() {
     let Node::Paragraph(line) = &nodes[0] else {
         panic!("a paragraph, not {:?}", nodes[0])
     };
-    assert_eq!(line.text, "Lift[a].");
-    assert_eq!(line.styles, [(4..7, Style::Footnote)]);
-    assert!(matches!(&nodes[1], Node::Footnote { label, body } if label == "a" && body.len() == 1));
+    assert_eq!(line.text, "Lift¹.");
+    assert_eq!(line.styles, [(4..6, Style::Footnote)]);
+    assert!(matches!(&nodes[1], Node::Footnote { label, body } if label == "1" && body.len() == 1));
+    let alone = parse(
+        "[^z]: Unread.
+",
+    );
+    assert!(matches!(&alone[0], Node::Footnote { label, .. } if label == "z"));
+}
+
+fn line(source: &str) -> Inline {
+    match parse(source).into_iter().next() {
+        Some(Node::Paragraph(text)) => text,
+        other => panic!("a paragraph, not {other:?}"),
+    }
+}
+
+#[test]
+fn inline_html_shows_as_typora_shows_it() {
+    let text = line(
+        "a <u>un</u> <b>bo</b> <kbd>K</kbd> <mark>hi</mark> <a href=\"https://ely.dev\">x</a><br>end <span>sp</span> <a name=\"n\">no</a>",
+    );
+    assert_eq!(text.text, "a un bo K hi x\nend sp no");
+    assert_eq!(
+        text.styles,
+        [
+            (2..4, Style::Underline),
+            (5..7, Style::Strong),
+            (8..9, Style::Code),
+            (10..12, Style::Mark),
+            (13..14, Style::Link)
+        ]
+    );
+    assert_eq!(text.links, [(13..14, "https://ely.dev".to_string())]);
+}
+
+/// Where `style` holds, touching stretches joined.
+fn marked(inline: &Inline, style: Style) -> Vec<(usize, usize)> {
+    let mut ranges: Vec<Range<usize>> = inline
+        .styles
+        .iter()
+        .filter(|(_, held)| *held == style)
+        .map(|(range, _)| range.clone())
+        .collect();
+    ranges.sort_by_key(|range| range.start);
+    let mut out: Vec<Range<usize>> = Vec::new();
+    for range in ranges {
+        match out.last_mut() {
+            Some(last) if last.end >= range.start => last.end = last.end.max(range.end),
+            _ => out.push(range),
+        }
+    }
+    out.into_iter()
+        .map(|range| (range.start, range.end))
+        .collect()
+}
+
+#[test]
+fn tags_and_emphasis_cross_as_a_browser_repairs_them() {
+    let opened_inside = line("**a <u>b** c</u> d");
+    assert_eq!(opened_inside.text, "a b c d");
+    assert_eq!(marked(&opened_inside, Style::Strong), [(0, 3)]);
+    assert_eq!(marked(&opened_inside, Style::Underline), [(2, 5)]);
+    let closed_inside = line("a <u>*text</u> outside* end");
+    assert_eq!(closed_inside.text, "a text outside end");
+    assert_eq!(marked(&closed_inside, Style::Underline), [(2, 6)]);
+    assert_eq!(marked(&closed_inside, Style::Emphasis), [(2, 14)]);
+    assert!(line("a </u> b").styles.is_empty(), "a stray close");
+}
+
+#[test]
+fn a_raw_close_ends_the_markdown_element() {
+    let em = line("a *inside</em> outside* end");
+    assert_eq!(em.text, "a inside outside end");
+    assert_eq!(marked(&em, Style::Emphasis), [(2, 8)]);
+    let strong = line("a **inside</strong> outside** end");
+    assert_eq!(marked(&strong, Style::Strong), [(2, 8)]);
+}
+
+#[test]
+fn only_formatting_elements_reopen_past_a_close() {
+    for (tag, style) in [
+        ("mark", Style::Mark),
+        ("kbd", Style::Code),
+        ("del", Style::Strike),
+    ] {
+        let text = line(&format!("a **bold <{tag}>x** outside</{tag}> end"));
+        assert_eq!(text.text, "a bold x outside end", "{tag}");
+        assert_eq!(marked(&text, style), [(7, 8)], "{tag}");
+    }
+    let reopened = line("<b>1<i>2</b>3</i>4");
+    assert_eq!(marked(&reopened, Style::Strong), [(0, 2)]);
+    assert_eq!(marked(&reopened, Style::Emphasis), [(1, 3)]);
+}
+
+#[test]
+fn a_new_anchor_ends_the_open_one() {
+    let text = line("[one <a href='/inner'>two</a> three](/outer)");
+    assert_eq!(text.text, "one two three");
+    assert_eq!(
+        text.links,
+        [(0..4, "/outer".to_string()), (4..7, "/inner".to_string())]
+    );
+    assert_eq!(marked(&text, Style::Link), [(0, 7)]);
+    let named = line("[x <a name=n>y</a> z](/u)");
+    assert_eq!(named.links, [(0..2, "/u".to_string())]);
+}
+
+#[test]
+fn a_closing_br_breaks_as_html_reads_it() {
+    assert_eq!(line("before<br></br>after").text, "before\n\nafter");
+}
+
+#[test]
+fn shortcodes_mean_what_github_means() {
+    assert_eq!(line(":cricket: :cricket_game:").text, "🦗 🏏");
+}
+
+#[test]
+fn shortcodes_draw_as_emoji_outside_code() {
+    let text = line("go :rocket: `:rocket:`");
+    assert_eq!(text.text, "go 🚀 :rocket:");
+}
+
+#[test]
+fn footnotes_number_by_their_first_reference() {
+    let nodes = parse("x[^b] y[^a] z[^b]\n\n[^a]: A\n\n[^b]: B\n");
+    let Node::Paragraph(text) = &nodes[0] else {
+        panic!("a paragraph, not {:?}", nodes[0])
+    };
+    assert_eq!(text.text, "x¹ y² z¹");
+    let labels: Vec<&str> = nodes[1..]
+        .iter()
+        .map(|node| match node {
+            Node::Footnote { label, .. } => label.as_str(),
+            other => panic!("a footnote, not {other:?}"),
+        })
+        .collect();
+    assert_eq!(labels, ["2", "1"]);
+}
+
+#[test]
+fn one_tilde_still_strikes() {
+    assert_eq!(line("H~2~O").styles, [(1..2, Style::Strike)]);
+}
+
+#[test]
+fn shortcodes_read_as_github_reads_them() {
+    let decoded = line(r"Show \:smile: and &#58;smile: and :sm&#105;le:.");
+    assert_eq!(decoded.text, "Show 😄 and 😄 and 😄.");
+    let tags = line("a <code>:smile:</code> <kbd>:smile:</kbd> <tt>:smile:</tt> :smile:");
+    assert_eq!(tags.text, "a :smile: 😄 😄 😄");
+    assert_eq!(
+        line("<https://x.test/:smile:>").text,
+        "https://x.test/:smile:"
+    );
+    assert_eq!(line("[go :smile:](https://x.test)").text, "go 😄");
+}
+
+#[test]
+fn unknown_tags_show_text_and_only_anchors_link() {
+    let custom = line("a <u-box>word</u-box> <br-box>in</br-box> end");
+    assert_eq!(
+        (custom.text.as_str(), custom.styles.len()),
+        ("a word in end", 0)
+    );
+    let bold = line("See <b href=\"https://x.test/\">bold</b>.");
+    assert_eq!(bold.styles, [(4..8, Style::Strong)]);
+    assert!(bold.links.is_empty(), "{bold:?}");
+    let query = line("<a href=\"https://x.test/?q=1&amp;p=2\">r</a> <a href=/path/>s</a>");
+    let urls: Vec<&str> = query.links.iter().map(|(_, url)| url.as_str()).collect();
+    assert_eq!(urls, ["https://x.test/?q=1&p=2", "/path/"]);
 }