documents: shortcodes read per DOM text node as GitHub reads them; HTML5's p closers end a p; a TOC press follows editor anchors

- The first `:name:`-shaped run in a text node decides for the whole node:
  blank text or a space before it turns every shortcode, else none. Filtered
  tags are text and do not split the node. Probed on GitHub's markdown API.
- `fieldset`, `menu` and the rest of HTML5's list end an open `p`.
- `CodeEditor` carries owner anchors through each edit; the document anchors
  every heading it reads, and a TOC press goes where its anchor went.

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. 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.
+- 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; within one DOM text node, which filtered tags do not split, the first `:name:`-shaped run decides for all: blank text or a space before it turns every shortcode, else none, so `x:smile: :smile:` stays), inline HTML's `u`, `b`/`strong`, `i`/`em`, `s`/`del`/`strike`, `code`/`kbd`, `mark`, `br` and `a href` draw as what they mean GFM's filtered tags (`script`, `style`, `title`, `textarea`, `iframe`, `xmp`, `noembed`, `noframes`, `plaintext`) show as text, and other tags, hyphenated names too, vanish, leaving their text; a tag's name runs to white space or `/`, as HTML5 reads it; 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. At the root, blocks read as GitHub shows them: a quote whose first line is plain text reading `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` in any case, after escapes and references, spaces and tabs around it, with more after it, is an alert under its title (Important in the palette's violet, `syntax.keyword`, read at 4.5:1); a paragraph that is `[toc]` alone, as Typora reads it, lists every heading by depth, and a press on one reveals it as a link press does (`MarkdownDocument`'s `reveal`), the heading found where `CodeEditor` anchors carried it through each edit since the read, gone if an edit or an undo took it, and a secondary press acts on press, since a block writing back moves the list; front matter shows in a box without its fences; an HTML block shows its text with the inline tags above, white space collapsed and owed as a browser lays it, block elements breaking lines and closing what opened inside them, HTML5's start tags ending an open `p`, `fieldset` and `menu` too, and an `li` start an `li`, a `dd` or `dt` start either, as HTML5 ends them, comments dropped, the filtered tags shown as text, and an unclosed tag dropping the rest; a rule is a 2px `border_strong` line; bullets go •, ◦, ▪ by list depth, ordered lists counted. `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 fartLine truncated
 - 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.

assets/icons/message-square-warning.svg

@@ -0,0 +1,17 @@
+<!-- @license lucide-static v1.48.0 - ISC -->
+<svg
+  class="lucide lucide-message-square-warning"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M22 17a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.71.71 0 0 1 2 21.286V5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2z" />
+  <path d="M12 15h.01" />
+  <path d="M12 7v4" />
+</svg>

src/documents/document/mod.rs

@@ -19,13 +19,18 @@ use gpui::{
     ListState, Pixels, Subscription, Task, Window,
 };
 
+pub use crate::documents::tree::DocumentHeading;
 pub use attach::Attachment;
 pub use look::DocumentLook;
-pub use parse::DocumentHeading;
 use parse::{Parsed, alike, parsed};
 pub use tables::{TableEdit, TableRefusal};
 
-use super::{MarkdownMode, markdown::markdown_highlights, modes::joint, render::OnLink};
+use super::{
+    MarkdownMode,
+    markdown::markdown_highlights,
+    modes::joint,
+    render::{OnHeading, OnLink},
+};
 use crate::{
     editor::{CodeEditor, EditorEvent, LineNumbers},
     forms::TextInput,
@@ -94,6 +99,7 @@ pub struct MarkdownDocument {
     centered: Option<(usize, u64, u64, [u64; 2])>,
     focus: FocusHandle,
     on_link: Option<OnLink>,
+    on_heading: Option<OnHeading>,
     _subscriptions: Vec<Subscription>,
 }
 
@@ -132,6 +138,11 @@ impl MarkdownDocument {
             cx.on_focus(&focus, window, Self::focused),
         ];
         let overdraw = window.rem_size() * 40.0;
+        let this = cx.entity().downgrade();
+        let on_heading: OnHeading = Rc::new(move |at, window, cx| {
+            this.update(cx, |document, cx| document.reveal_at(at, window, cx))
+                .expect("a heading list lives in its document");
+        });
         let mut document = Self {
             editor,
             mode,
@@ -151,6 +162,7 @@ impl MarkdownDocument {
             room: Pixels::ZERO,
             focus,
             on_link: None,
+            on_heading: Some(on_heading),
             _subscriptions: subscriptions,
         };
         document.reparse(true, cx);
@@ -304,6 +316,9 @@ impl MarkdownDocument {
         let old = self.parsed.blocks.len();
         self.list
             .splice(head..old - tail, read.blocks.len() - head - tail);
+        let headings: Vec<usize> = read.headings.iter().map(|heading| heading.at).collect();
+        self.editor
+            .update(cx, |editor, _| editor.set_anchors(headings));
         self.parsed = Arc::new(read);
         cx.emit(DocumentEvent::Parsed);
         cx.notify();

src/documents/document/parse.rs

@@ -3,27 +3,18 @@ use std::ops::Range;
 use markdown::mdast;
 
 use crate::documents::{
-    markdown::{file_tree, span, walk},
-    tree::{Node, Reader},
+    markdown::{file_tree, span},
+    tree::{DocumentHeading, Node, Reader},
 };
 
 /// A top-level block: its source, and what it draws.
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) struct Block {
     pub range: Range<usize>,
-    /// None shows the source as written: definitions, HTML, front matter.
+    /// None shows a link definition as written.
     pub nodes: Option<Vec<Node>>,
 }
 
-/// A heading anywhere in the file.
-#[derive(Clone, Debug, PartialEq)]
-pub struct DocumentHeading {
-    pub depth: u8,
-    pub title: String,
-    /// Where its source starts, in bytes.
-    pub at: usize,
-}
-
 /// A file read as blocks and headings.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub(crate) struct Parsed {
@@ -44,16 +35,10 @@ pub(crate) fn parsed(text: &str) -> Parsed {
         .map(|node| {
             let range = span(node);
             let kept = text[range.clone()].trim_end_matches(['\n', '\r']).len();
-            let raw = matches!(
-                node,
-                mdast::Node::Definition(_)
-                    | mdast::Node::Html(_)
-                    | mdast::Node::Yaml(_)
-                    | mdast::Node::Toml(_)
-            );
+            let raw = matches!(node, mdast::Node::Definition(_));
             let nodes = (!raw).then(|| {
                 let mut out = Vec::new();
-                reader.block(node, &mut out);
+                reader.top(node, &mut out);
                 out
             });
             Block {
@@ -62,23 +47,10 @@ pub(crate) fn parsed(text: &str) -> Parsed {
             }
         })
         .collect();
-    let mut nodes = Vec::new();
-    walk(&root, &mut nodes);
-    let headings = nodes
-        .into_iter()
-        .filter_map(|node| match node {
-            mdast::Node::Heading(heading) => Some(DocumentHeading {
-                depth: heading.depth,
-                title: reader.inline(&heading.children).text,
-                at: span(node).start,
-            }),
-            _ => None,
-        })
-        .collect();
     Parsed {
         text: text.to_string(),
         blocks,
-        headings,
+        headings: reader.headings,
     }
 }
 
@@ -111,7 +83,7 @@ mod tests {
     use crate::documents::tree::Style;
 
     #[test]
-    fn every_block_is_shown_raw_ones_as_written() {
+    fn every_block_is_shown_definitions_as_written() {
         let text = "---\ntitle: a\n---\n\n# Lift\n\n[site]: https://ely.dev\n\n<div>x</div>\n\n> ## Quoted\n";
         let found = parsed(text);
         let shown: Vec<(&str, bool)> = found
@@ -122,13 +94,16 @@ mod tests {
         assert_eq!(
             shown,
             [
-                ("---\ntitle: a\n---", false),
+                ("---\ntitle: a\n---", true),
                 ("# Lift", true),
                 ("[site]: https://ely.dev", false),
-                ("<div>x</div>", false),
+                ("<div>x</div>", true),
                 ("> ## Quoted", true),
             ]
         );
+        let drawn = |ix: usize| found.blocks[ix].nodes.clone().expect("drawn");
+        assert_eq!(drawn(0), [Node::FrontMatter("title: a".into())]);
+        assert!(matches!(&drawn(3)[..], [Node::Paragraph(line)] if line.text == "x"));
         let headings: Vec<(u8, &str, usize)> = found
             .headings
             .iter()

src/documents/document/place.rs

@@ -189,6 +189,35 @@ impl MarkdownDocument {
             .saturating_sub(1)
     }
 
+    /// Reveals the pressed heading where the edits since carried it.
+    pub(super) fn reveal_at(&mut self, at: usize, window: &mut Window, cx: &mut Context<Self>) {
+        let headings = &self.parsed.headings;
+        let Some(index) = headings.iter().position(|heading| heading.at == at) else {
+            return log::warn!("markdown document: a heading read away");
+        };
+        self.commit(cx);
+        let anchors = self.editor.read(cx).anchors();
+        let Some(found) = *anchors.get(index).expect("an anchor per heading read") else {
+            return log::warn!("markdown document: the pressed heading changed as one wrote");
+        };
+        if !self.read_now(cx) {
+            self.reparse(true, cx);
+        }
+        if !self.read_now(cx) {
+            return log::warn!("markdown document: a heading pressed while the text is read again");
+        }
+        if !self
+            .parsed
+            .headings
+            .iter()
+            .any(|heading| heading.at == found)
+        {
+            return log::warn!("markdown document: the pressed heading reads as no heading now");
+        }
+        let line = self.editor.read(cx).buffer.line_of(found);
+        self.reveal(line, window, cx);
+    }
+
     /// Line `line` at top and focused, caret at start.
     pub fn reveal(&mut self, line: usize, window: &mut Window, cx: &mut Context<Self>) {
         self.set_caret(line, 0, cx);

src/documents/document/tests/mod.rs

@@ -370,6 +370,7 @@ mod history;
 mod links;
 mod look;
 mod place;
+mod toc;
 mod tools;
 
 #[gpui::test]

src/documents/document/tests/toc.rs

@@ -0,0 +1,190 @@
+use gpui::{Entity, Modifiers, MouseButton, TestAppContext, VisualTestContext, point, px};
+
+use super::{MarkdownDocument, MarkdownMode, frames, open, type_in};
+
+const LISTED: &str = "[toc]\n\n# A\n\ntext\n\n## B\n";
+
+/// Presses entry `ix` of the drawn heading list.
+fn press_entry(ix: usize, modifiers: Modifiers, cx: &mut VisualTestContext) {
+    let bounds = cx
+        .debug_bounds(Box::leak(format!("markdown-toc-{ix}").into_boxed_str()))
+        .expect("the entry is drawn");
+    let at = point(bounds.left() + px(2.0), bounds.top() + px(2.0));
+    cx.simulate_mouse_down(at, MouseButton::Left, modifiers);
+    frames(cx);
+    cx.simulate_mouse_up(at, MouseButton::Left, modifiers);
+    cx.run_until_parked();
+}
+
+#[gpui::test]
+fn a_heading_written_above_with_the_same_title_is_not_the_pressed_one(cx: &mut TestAppContext) {
+    let text = "before\n\n[toc]\n\n# A\n\ntext\n\n## B\n";
+    let (document, cx) = open(text, MarkdownMode::Visual, cx);
+    type_in(&document, Some(0), Some("## B"), cx);
+    frames(cx);
+    press_entry(1, Modifiers::secondary_key(), cx);
+    let (caret, now) =
+        document.read_with(cx, |document, cx| (document.caret(cx), document.text(cx)));
+    assert_eq!(now, "## B\n\n[toc]\n\n# A\n\ntext\n\n## B\n");
+    assert_eq!(caret, (8, 0));
+}
+
+#[gpui::test]
+fn a_twin_typed_above_while_the_text_waits_is_not_the_pressed_one(cx: &mut TestAppContext) {
+    let (document, cx) = open(LISTED, MarkdownMode::Split, cx);
+    document.update(cx, |document, cx| {
+        document.editor.update(cx, |editor, cx| {
+            editor.edit([(0..0, "## B\n\n".to_string())], cx);
+        });
+    });
+    cx.run_until_parked();
+    assert!(!document.read_with(cx, |document, cx| document.read_now(cx)));
+    press_entry(1, Modifiers::none(), cx);
+    assert_eq!(
+        document.read_with(cx, |document, cx| document.caret(cx)),
+        (8, 0)
+    );
+}
+
+const TWINS: &str = "[toc]\n\n## B\n\ntext\n\n## B\n";
+
+/// Deletes the first twin while the text waits.
+fn delete_first_twin(document: &Entity<MarkdownDocument>, cx: &mut VisualTestContext) {
+    document.update(cx, |document, cx| {
+        document.editor.update(cx, |editor, cx| {
+            editor.edit([(7..13, String::new())], cx);
+        });
+    });
+    cx.run_until_parked();
+}
+
+#[gpui::test]
+fn a_deleted_twin_leaves_the_other_found(cx: &mut TestAppContext) {
+    let (document, cx) = open(TWINS, MarkdownMode::Split, cx);
+    delete_first_twin(&document, cx);
+    press_entry(1, Modifiers::none(), cx);
+    assert_eq!(
+        document.read_with(cx, |document, cx| document.caret(cx)),
+        (4, 0)
+    );
+}
+
+#[gpui::test]
+fn a_press_on_a_deleted_twin_moves_nothing(cx: &mut TestAppContext) {
+    let (document, cx) = open(TWINS, MarkdownMode::Split, cx);
+    delete_first_twin(&document, cx);
+    let before = document.read_with(cx, |document, cx| document.caret(cx));
+    press_entry(0, Modifiers::none(), cx);
+    assert_eq!(
+        document.read_with(cx, |document, cx| document.caret(cx)),
+        before
+    );
+}
+
+#[gpui::test]
+fn a_press_in_preview_reveals_the_heading(cx: &mut TestAppContext) {
+    let (document, cx) = open(LISTED, MarkdownMode::Preview, cx);
+    press_entry(1, Modifiers::none(), cx);
+    let caret = document.read_with(cx, |document, cx| document.caret(cx));
+    assert_eq!(caret, (6, 0));
+}
+
+#[gpui::test]
+fn visual_reveals_on_a_secondary_press_and_edits_on_a_plain_one(cx: &mut TestAppContext) {
+    let (document, cx) = open(LISTED, MarkdownMode::Visual, cx);
+    press_entry(1, Modifiers::secondary_key(), cx);
+    let (caret, open) = document.read_with(cx, |document, cx| {
+        (document.caret(cx), document.open.is_some())
+    });
+    assert_eq!((caret, open), ((6, 0), false));
+    press_entry(0, Modifiers::none(), cx);
+    assert!(document.read_with(cx, |document, _| document.open.is_some()));
+}
+
+#[gpui::test]
+fn a_press_after_an_earlier_block_grew_finds_the_heading(cx: &mut TestAppContext) {
+    let text = "before\n\n[toc]\n\n# A\n\ntext\n\n## B\n";
+    let (document, cx) = open(text, MarkdownMode::Visual, cx);
+    type_in(&document, Some(0), Some("before\nextra\nextra"), cx);
+    frames(cx);
+    press_entry(1, Modifiers::secondary_key(), cx);
+    frames(cx);
+    assert_eq!(
+        document.read_with(cx, |document, cx| document.caret(cx)),
+        (10, 0)
+    );
+}
+
+#[gpui::test]
+fn a_press_while_the_text_waits_to_be_read_finds_the_heading(cx: &mut TestAppContext) {
+    let (document, cx) = open(LISTED, MarkdownMode::Split, cx);
+    document.update(cx, |document, cx| {
+        document.editor.update(cx, |editor, cx| {
+            editor.edit([(0..0, "inserted\n".repeat(20))], cx);
+        });
+    });
+    cx.run_until_parked();
+    assert!(!document.read_with(cx, |document, cx| document.read_now(cx)));
+    press_entry(1, Modifiers::none(), cx);
+    frames(cx);
+    assert_eq!(
+        document.read_with(cx, |document, cx| document.caret(cx)),
+        (26, 0)
+    );
+}
+
+/// Makes `edits` while the text waits, caret at the top.
+fn edit_waiting<'a>(
+    text: &str,
+    edits: Vec<(std::ops::Range<usize>, String)>,
+    cx: &'a mut TestAppContext,
+) -> (Entity<MarkdownDocument>, &'a mut VisualTestContext) {
+    let (document, cx) = open(text, MarkdownMode::Split, cx);
+    document.update(cx, |document, cx| {
+        document
+            .editor
+            .update(cx, |editor, cx| editor.edit(edits, cx));
+        document.set_caret(0, 0, cx);
+    });
+    frames(cx);
+    assert!(!document.read_with(cx, |document, cx| document.read_now(cx)));
+    (document, cx)
+}
+
+fn caret(document: &Entity<MarkdownDocument>, cx: &mut VisualTestContext) -> (usize, usize) {
+    document.read_with(cx, |document, cx| document.caret(cx))
+}
+
+#[gpui::test]
+fn a_twin_written_right_at_the_heading_goes_before_it(cx: &mut TestAppContext) {
+    let edits = vec![(7..7, "## B\n\n".to_string())];
+    let (document, cx) = edit_waiting("[toc]\n\n## B\n\ntext\n", edits, cx);
+    press_entry(0, Modifiers::none(), cx);
+    assert_eq!(caret(&document, cx), (4, 0));
+}
+
+#[gpui::test]
+fn adjacent_twins_keep_who_was_deleted(cx: &mut TestAppContext) {
+    let twins = "[toc]\n\n## B\n\n## B\n\ntext\n";
+    let (document, cx) = edit_waiting(twins, vec![(7..13, String::new())], cx);
+    press_entry(0, Modifiers::none(), cx);
+    assert_eq!(
+        caret(&document, cx),
+        (0, 0),
+        "the deleted one moves nothing"
+    );
+    press_entry(1, Modifiers::none(), cx);
+    assert_eq!(caret(&document, cx), (2, 0), "the kept one moved up");
+}
+
+#[gpui::test]
+fn a_heading_between_two_edits_stays_found(cx: &mut TestAppContext) {
+    let text = "before\n\n[toc]\n\n# A\n\nafter\n";
+    let edits = vec![
+        (0..0, "start\n".to_string()),
+        (text.len()..text.len(), "end\n".to_string()),
+    ];
+    let (document, cx) = edit_waiting(text, edits, cx);
+    press_entry(0, Modifiers::none(), cx);
+    assert_eq!(caret(&document, cx), (5, 0));
+}

src/documents/document/visual.rs

@@ -101,6 +101,7 @@ impl MarkdownDocument {
                     nodes,
                     &self.base,
                     &self.on_link,
+                    &self.on_heading,
                     self.look.scale,
                     cx,
                 )),

src/documents/render.rs

@@ -16,12 +16,16 @@ use super::{
 use crate::{
     editor::{code_colors, code_colors_with},
     navigation::{Anchor, Sections},
-    primitives::{FocusRing as _, Icon, IconName},
-    theme::{ActiveTheme, IconSize, Radius, TextSize},
+    primitives::FocusRing as _,
+    theme::{ActiveTheme, Radius, TextSize},
     typography::{Latex, failed},
 };
 
+mod blocks;
+
 pub(crate) type OnLink = Rc<dyn Fn(&str, &mut Window, &mut App)>;
+/// Reveals the heading whose source starts at a byte.
+pub(crate) type OnHeading = Rc<dyn Fn(usize, &mut Window, &mut App)>;
 type DrawCode = Rc<dyn Fn(ElementId, Option<SharedString>, SharedString) -> AnyElement>;
 
 /// Markdown drawn as a document; links go to the host.
@@ -94,6 +98,9 @@ struct Draw<'a> {
     base: &'a Option<Arc<Path>>,
     /// Text size against the theme's.
     scale: f32,
+    /// Lists open around the node drawn.
+    lists: std::cell::Cell<usize>,
+    on_heading: &'a Option<OnHeading>,
 }
 
 impl Draw<'_> {
@@ -263,58 +270,7 @@ impl Draw<'_> {
                     .child(StyledText::new(text.clone()).with_highlights(styles))
                     .into_any_element()
             }
-            Node::List { start, items } => div()
-                .flex()
-                .flex_col()
-                .gap_1()
-                .children(items.iter().enumerate().map(|(ix, (task, body))| {
-                    let marker: AnyElement = match (task, start) {
-                        (Some(done), _) => Icon::new(if *done {
-                            IconName::SquareCheck
-                        } else {
-                            IconName::Square
-                        })
-                        .size(IconSize::Sm)
-                        .color(if *done {
-                            colors.focus
-                        } else {
-                            colors.fg_subtle
-                        })
-                        .into_any_element(),
-                        (None, Some(first)) => div()
-                            .text_color(colors.fg_muted)
-                            .child(format!("{}.", first + ix as u64))
-                            .into_any_element(),
-                        (None, None) => div()
-                            .text_color(colors.fg_muted)
-                            .child("•")
-                            .into_any_element(),
-                    };
-                    div()
-                        .flex()
-                        .gap_2()
-                        .child(
-                            div()
-                                .flex_none()
-                                .min_w_5()
-                                .flex()
-                                .justify_end()
-                                .child(marker),
-                        )
-                        .child(
-                            div()
-                                .flex_1()
-                                .min_w_0()
-                                .flex()
-                                .flex_col()
-                                .gap_1()
-                                .when(*task == Some(true), |body| {
-                                    body.text_color(colors.fg_subtle)
-                                })
-                                .children(self.nodes(body, cx)),
-                        )
-                }))
-                .into_any_element(),
+            Node::List { start, items } => self.list(start, items, cx),
             Node::Table { aligns, head, rows } => {
                 let cell = |blocks: &[Node], column: usize, header: bool, cx: &App| {
                     div()
@@ -370,10 +326,10 @@ impl Draw<'_> {
                     .into_any_element()
             }
             Node::Rule => div()
+                .debug_selector(|| "markdown-rule".into())
                 .my_2()
-                .h_0()
-                .border_t_1()
-                .border_color(colors.border)
+                .border_t_2()
+                .border_color(colors.border_strong)
                 .into_any_element(),
             Node::Math(tex) => div()
                 .flex()
@@ -416,6 +372,9 @@ impl Draw<'_> {
                         .children(self.nodes(body, cx)),
                 )
                 .into_any_element(),
+            Node::Alert { kind, body } => self.alert(*kind, body, cx),
+            Node::Toc(headings) => self.toc(headings, cx),
+            Node::FrontMatter(text) => self.front_matter(text, cx),
         }
     }
 }
@@ -436,6 +395,7 @@ pub(crate) fn draw_nodes(
     nodes: &[Node],
     base: &Option<Arc<Path>>,
     on_link: &Option<OnLink>,
+    on_heading: &Option<OnHeading>,
     scale: f32,
     cx: &App,
 ) -> Vec<AnyElement> {
@@ -448,6 +408,8 @@ pub(crate) fn draw_nodes(
         code: &None,
         base,
         scale,
+        lists: std::cell::Cell::new(0),
+        on_heading,
     };
     draw.nodes(nodes, cx)
 }
@@ -465,6 +427,8 @@ impl RenderOnce for MarkdownRenderer {
             code: &self.code,
             base: &self.base,
             scale: 1.0,
+            lists: std::cell::Cell::new(0),
+            on_heading: &None,
         };
         div()
             .flex()
@@ -475,3 +439,6 @@ impl RenderOnce for MarkdownRenderer {
             .children(draw.nodes(&nodes, cx))
     }
 }
+
+#[cfg(test)]
+mod tests;

src/documents/render/blocks.rs

@@ -0,0 +1,186 @@
+use gpui::{
+    AnyElement, App, FontWeight, IntoElement, MouseButton, ParentElement, Styled, div, prelude::*,
+};
+
+use super::Draw;
+use crate::{
+    documents::tree::{AlertKind, DocumentHeading, Node},
+    primitives::{FocusRing as _, Icon, IconName},
+    theme::{ActiveTheme, IconSize, Radius, TextSize},
+};
+
+impl Draw<'_> {
+    /// A list; bullets turn with depth, as browsers draw them.
+    pub(super) fn list(
+        &self,
+        start: &Option<u64>,
+        items: &[(Option<bool>, Vec<Node>)],
+        cx: &App,
+    ) -> AnyElement {
+        let colors = cx.theme().colors.clone();
+        let depth = self.lists.get();
+        self.lists.set(depth + 1);
+        let bullet = match depth {
+            0 => "•",
+            1 => "◦",
+            _ => "▪",
+        };
+        let list = div()
+            .flex()
+            .flex_col()
+            .gap_1()
+            .children(items.iter().enumerate().map(|(ix, (task, body))| {
+                let marker: AnyElement = match (task, start) {
+                    (Some(done), _) => Icon::new(if *done {
+                        IconName::SquareCheck
+                    } else {
+                        IconName::Square
+                    })
+                    .size(IconSize::Sm)
+                    .color(if *done {
+                        colors.focus
+                    } else {
+                        colors.fg_subtle
+                    })
+                    .into_any_element(),
+                    (None, Some(first)) => div()
+                        .text_color(colors.fg_muted)
+                        .child(format!("{}.", first + ix as u64))
+                        .into_any_element(),
+                    (None, None) => div()
+                        .debug_selector(move || format!("markdown-bullet-{depth}"))
+                        .text_color(colors.fg_muted)
+                        .child(bullet)
+                        .into_any_element(),
+                };
+                div()
+                    .flex()
+                    .gap_2()
+                    .child(
+                        div()
+                            .flex_none()
+                            .min_w_5()
+                            .flex()
+                            .justify_end()
+                            .child(marker),
+                    )
+                    .child(
+                        div()
+                            .flex_1()
+                            .min_w_0()
+                            .flex()
+                            .flex_col()
+                            .gap_1()
+                            .when(*task == Some(true), |body| {
+                                body.text_color(colors.fg_subtle)
+                            })
+                            .children(self.nodes(body, cx)),
+                    )
+            }))
+            .into_any_element();
+        self.lists.set(depth);
+        list
+    }
+
+    /// A GitHub alert: a colored rule, icon, title and body.
+    pub(super) fn alert(&self, kind: AlertKind, body: &[Node], cx: &App) -> AnyElement {
+        let colors = &cx.theme().colors;
+        let (tone, icon) = match kind {
+            AlertKind::Note => (colors.info, IconName::Info),
+            AlertKind::Tip => (colors.success, IconName::Lightbulb),
+            // The palette's violet, read at 4.5:1.
+            AlertKind::Important => (colors.syntax.keyword, IconName::MessageSquareWarning),
+            AlertKind::Warning => (colors.warning, IconName::TriangleAlert),
+            AlertKind::Caution => (colors.danger, IconName::OctagonAlert),
+        };
+        div()
+            .flex()
+            .flex_col()
+            .gap_1()
+            .py_1()
+            .pl_4()
+            .border_l_2()
+            .border_color(tone)
+            .child(
+                div()
+                    .flex()
+                    .items_center()
+                    .gap_2()
+                    .font_weight(FontWeight::MEDIUM)
+                    .text_color(tone)
+                    .child(Icon::new(icon).size(IconSize::Sm).color(tone))
+                    .child(kind.title()),
+            )
+            .child(
+                div()
+                    .flex()
+                    .flex_col()
+                    .gap_2()
+                    .text_color(colors.fg)
+                    .children(self.nodes(body, cx)),
+            )
+            .into_any_element()
+    }
+
+    /// `[toc]`: each heading by depth; a press reveals it.
+    pub(super) fn toc(&self, headings: &[DocumentHeading], cx: &App) -> AnyElement {
+        let colors = cx.theme().colors.clone();
+        let top = headings.iter().map(|heading| heading.depth).min();
+        div()
+            .flex()
+            .flex_col()
+            .gap_1()
+            .children(headings.iter().enumerate().map(|(ix, heading)| {
+                let entry = div()
+                    .id(self.key("toc"))
+                    .debug_selector(move || format!("markdown-toc-{ix}"))
+                    .child(heading.title.clone());
+                let entry = match heading.depth - top.expect("a heading is listed") {
+                    0 => entry,
+                    1 => entry.pl_4(),
+                    2 => entry.pl_8(),
+                    3 => entry.pl_12(),
+                    4 => entry.pl_16(),
+                    _ => entry.pl_20(),
+                };
+                let Some(reveal) = self.on_heading.clone() else {
+                    return entry.text_color(colors.fg_muted).into_any_element();
+                };
+                let (at, pressed) = (heading.at, reveal.clone());
+                entry
+                    .text_color(colors.link)
+                    .tab_index(0)
+                    .focus_ring(cx)
+                    .cursor_pointer()
+                    // On press: the layout may move before release.
+                    .on_mouse_down(MouseButton::Left, move |event, window, cx| {
+                        if event.modifiers.secondary() {
+                            window.prevent_default();
+                            cx.stop_propagation();
+                            pressed(at, window, cx);
+                        }
+                    })
+                    .on_click(move |event, window, cx| {
+                        if !event.modifiers().secondary() {
+                            reveal(at, window, cx);
+                        }
+                    })
+                    .into_any_element()
+            }))
+            .into_any_element()
+    }
+
+    /// Front matter as written, inside its box.
+    pub(super) fn front_matter(&self, text: &str, cx: &App) -> AnyElement {
+        let theme = cx.theme();
+        div()
+            .p_3()
+            .rounded(theme.radius(Radius::Md))
+            .bg(theme.colors.sunken)
+            .font_family(theme.mono_family.clone())
+            .text_size(theme.text_size(TextSize::Sm) * self.scale)
+            .text_color(theme.colors.fg_muted)
+            .child(text.to_string())
+            .into_any_element()
+    }
+}

src/documents/render/tests.rs

@@ -0,0 +1,53 @@
+use gpui::{Context, IntoElement, Render, TestAppContext, Window, div, prelude::*, px};
+
+use super::MarkdownRenderer;
+use crate::theme::Theme;
+
+/// `source` drawn in a 400-point column.
+struct Page(&'static str);
+
+impl Render for Page {
+    fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
+        div()
+            .w(px(400.0))
+            .child(MarkdownRenderer::new("page", self.0))
+    }
+}
+
+#[gpui::test]
+fn a_rule_draws_a_line_two_pixels_high(cx: &mut TestAppContext) {
+    cx.update(Theme::init);
+    let (_, cx) = cx.add_window_view(|_, _| Page("above\n\n---\n\nbelow\n"));
+    cx.run_until_parked();
+    let rule = cx.debug_bounds("markdown-rule").expect("the rule is drawn");
+    assert_eq!(rule.size.height, px(2.0), "{rule:?}");
+    assert!(rule.size.width > px(300.0), "{rule:?}");
+}
+
+#[gpui::test]
+fn bullets_turn_with_depth(cx: &mut TestAppContext) {
+    cx.update(Theme::init);
+    let (_, cx) = cx.add_window_view(|_, _| Page("- a\n  - b\n    1. c\n       - d\n"));
+    cx.run_until_parked();
+    for depth in [0, 1, 3] {
+        let selector = Box::leak(format!("markdown-bullet-{depth}").into_boxed_str());
+        assert!(cx.debug_bounds(selector).is_some(), "depth {depth}");
+    }
+    assert!(
+        cx.debug_bounds("markdown-bullet-2").is_none(),
+        "an ordered list"
+    );
+}
+
+#[gpui::test]
+fn alerts_lists_of_headings_and_front_matter_draw(cx: &mut TestAppContext) {
+    cx.update(Theme::init);
+    let source = "> [!IMPORTANT]\n> read\n\n[toc]\n\n# One\n\n## Two\n";
+    let (_, cx) = cx.add_window_view(|_, _| Page(source));
+    cx.run_until_parked();
+    let (one, two) = (
+        cx.debug_bounds("markdown-toc-0").expect("drawn"),
+        cx.debug_bounds("markdown-toc-1").expect("drawn"),
+    );
+    assert!(two.top() > one.top(), "{one:?} {two:?}");
+}

src/documents/tree/blocks.rs

@@ -0,0 +1,486 @@
+use markdown::mdast;
+
+use super::{Node, Reader, Run, html, text_block};
+use crate::documents::markdown::span;
+
+/// A heading anywhere in the file.
+#[derive(Clone, Debug, PartialEq)]
+pub struct DocumentHeading {
+    pub depth: u8,
+    pub title: String,
+    /// Where its source starts, in bytes.
+    pub at: usize,
+}
+
+/// A GitHub alert's kind, named by its marker.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum AlertKind {
+    Note,
+    Tip,
+    Important,
+    Warning,
+    Caution,
+}
+
+impl AlertKind {
+    /// The title GitHub shows.
+    pub fn title(self) -> &'static str {
+        match self {
+            Self::Note => "Note",
+            Self::Tip => "Tip",
+            Self::Important => "Important",
+            Self::Warning => "Warning",
+            Self::Caution => "Caution",
+        }
+    }
+
+    /// The kind `line` marks, as `[!NOTE]` in any case.
+    fn marked(line: &str) -> Option<Self> {
+        let name = line
+            .trim_matches([' ', '\t'])
+            .strip_prefix("[!")?
+            .strip_suffix(']')?;
+        [
+            Self::Note,
+            Self::Tip,
+            Self::Important,
+            Self::Warning,
+            Self::Caution,
+        ]
+        .into_iter()
+        .find(|kind| kind.title().eq_ignore_ascii_case(name))
+    }
+}
+
+impl Reader<'_> {
+    /// A root block; alerts and `[toc]` live only here.
+    pub(crate) fn top(&self, node: &mdast::Node, out: &mut Vec<Node>) {
+        if let Some(alert) = self.alert(node) {
+            return out.push(alert);
+        }
+        let toc = matches!(node, mdast::Node::Paragraph(_))
+            && self.source[span(node)].trim().eq_ignore_ascii_case("[toc]");
+        match toc {
+            true => out.push(Node::Toc(self.headings.clone())),
+            false => self.block(node, out),
+        }
+    }
+
+    /// A quote whose first line marks it, with more after.
+    fn alert(&self, node: &mdast::Node) -> Option<Node> {
+        let mdast::Node::Blockquote(quote) = node else {
+            return None;
+        };
+        let [mdast::Node::Paragraph(paragraph), rest @ ..] = &quote.children[..] else {
+            return None;
+        };
+        let (kind, after) = marker(&paragraph.children)?;
+        if after.is_empty() && rest.is_empty() {
+            return None;
+        }
+        let mut body = Vec::new();
+        if !after.is_empty() {
+            let kept = mdast::Paragraph {
+                children: after,
+                position: paragraph.position.clone(),
+            };
+            self.block(&mdast::Node::Paragraph(kept), &mut body);
+        }
+        self.blocks(rest, &mut body);
+        Some(Node::Alert { kind, body })
+    }
+
+    /// An HTML block's text, as a browser shows it.
+    pub(super) fn html_block(&self, written: &str, out: &mut Vec<Node>) {
+        let mut run = Run::default();
+        let mut rest = written;
+        while let Some(at) = rest.find('<') {
+            run.words(&rest[..at]);
+            rest = &rest[at..];
+            if let Some(comment) = rest.strip_prefix("<!--") {
+                rest = comment.split_once("-->").map_or("", |(_, after)| after);
+                run.shortcodes.split();
+                continue;
+            }
+            let opens =
+                rest[1..].starts_with(|ch: char| ch.is_ascii_alphabetic() || "/!?".contains(ch));
+            if !opens {
+                run.words("<");
+                rest = &rest[1..];
+                continue;
+            }
+            // An unclosed tag drops the rest, as HTML5 does.
+            let Some(end) = html::tag_end(rest) else {
+                rest = "";
+                break;
+            };
+            let (written, after) = rest.split_at(end);
+            rest = after;
+            match html::tag(written) {
+                Some(tag) if html::filtered(&tag.name) => run.words(written),
+                // A block closes what opened inside it.
+                Some(tag) if html::breaks(&tag.name) => {
+                    run.line();
+                    match tag.closing {
+                        true => run.end(&tag.name),
+                        false => {
+                            run.implied(&tag.name);
+                            match tag.name == "hr" {
+                                true => run.shortcodes.split(),
+                                false => run.start(&tag.name, None, None),
+                            }
+                        }
+                    }
+                }
+                // It ends a `p` but lays no block.
+                Some(tag) if !tag.closing && html::closes_p(&tag.name) => {
+                    run.implied(&tag.name);
+                    run.html(written);
+                }
+                // A line's end drops its space.
+                Some(tag) if tag.closing || tag.name == "br" => {
+                    run.owed = run.owed.filter(|_| tag.name != "br");
+                    run.html(written);
+                }
+                Some(_) => {
+                    run.pay();
+                    run.html(written);
+                }
+                None => run.shortcodes.split(),
+            }
+        }
+        run.words(rest);
+        text_block(run.cut(), out);
+    }
+}
+
+impl Run {
+    /// HTML text: references decoded, white space collapsed.
+    fn words(&mut self, written: &str) {
+        let shown = self.shown(&html::text(written));
+        self.spaced(&shown);
+    }
+
+    /// Text with its white space collapsed.
+    fn spaced(&mut self, shown: &str) {
+        for ch in shown.chars() {
+            if !html::spacing(ch) {
+                self.pay();
+                self.text.text.push(ch);
+            } else if self.owed.is_none() && !self.text.text.ends_with('\n') {
+                let open = self.open.len();
+                self.owed = (!self.text.text.is_empty()).then_some((' ', open));
+            }
+        }
+    }
+
+    /// A line owed where a block element starts or ends.
+    fn line(&mut self) {
+        let from = self.owed.map_or(self.open.len(), |(_, from)| from);
+        let text = &self.text.text;
+        self.owed = (!(text.is_empty() || text.ends_with('\n'))).then_some(('\n', from));
+    }
+
+    /// Writes the white space owed, before a word or tag.
+    fn pay(&mut self) {
+        let Some((owed, from)) = self.owed.take() else {
+            return;
+        };
+        self.text.text.push(owed);
+        let start = self.text.text.len();
+        // What opened after it starts after it.
+        for opened in &mut self.open[from..] {
+            opened.start = start;
+        }
+    }
+
+    /// Ends what a block's start tag closes, as HTML5 does.
+    fn implied(&mut self, name: &str) {
+        let items: &[&str] = match name {
+            "li" => &["li"],
+            "dd" | "dt" => &["dd", "dt"],
+            _ => &[],
+        };
+        // The search stops at a special element.
+        let stops = |name: &str| html::breaks(name) && !matches!(name, "address" | "div" | "p");
+        let found = items
+            .iter()
+            .any(|item| self.count(item) > 0)
+            .then(|| {
+                let mut names = self.open.iter().rev().map(|opened| opened.name.as_str());
+                names.find(|name| items.contains(name) || stops(name))
+            })
+            .flatten()
+            .filter(|name| items.contains(name))
+            .map(str::to_string);
+        if let Some(item) = found {
+            self.end(&item);
+        }
+        if html::closes_p(name) && self.count("p") > 0 {
+            self.line();
+            self.end("p");
+        }
+    }
+}
+
+/// A plain first line naming a kind, and what follows.
+fn marker(children: &[mdast::Node]) -> Option<(AlertKind, Vec<mdast::Node>)> {
+    let mut line = String::new();
+    for (at, child) in children.iter().enumerate() {
+        let head = match child {
+            mdast::Node::Text(text) => match text.value.find(['\n', '\r']) {
+                None => {
+                    line.push_str(&text.value);
+                    continue;
+                }
+                Some(end) => {
+                    line.push_str(&text.value[..end]);
+                    let after = &text.value[end..];
+                    let after = after.strip_prefix("\r\n").unwrap_or(&after[1..]);
+                    let mut kept = text.clone();
+                    kept.value = after.to_string();
+                    (!after.is_empty()).then_some(mdast::Node::Text(kept))
+                }
+            },
+            mdast::Node::Break(_) => None,
+            _ => return None,
+        };
+        let after = head.into_iter().chain(children[at + 1..].iter().cloned());
+        return Some((AlertKind::marked(&line)?, after.collect()));
+    }
+    Some((AlertKind::marked(&line)?, Vec::new()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::documents::tree::{Inline, Style, parse};
+
+    fn alert(source: &str) -> Option<(AlertKind, Vec<Node>)> {
+        match parse(source).into_iter().next() {
+            Some(Node::Alert { kind, body }) => Some((kind, body)),
+            _ => None,
+        }
+    }
+
+    fn text(nodes: &[Node]) -> Vec<String> {
+        nodes
+            .iter()
+            .map(|node| match node {
+                Node::Paragraph(line) => line.text.clone(),
+                Node::Heading(_, line) => format!("# {}", line.text),
+                other => format!("{other:?}"),
+            })
+            .collect()
+    }
+
+    #[test]
+    fn alerts_read_as_github_reads_them() {
+        let note = alert("> [!NOTE]\n> one").expect("an alert");
+        assert_eq!(
+            (note.0, text(&note.1)),
+            (AlertKind::Note, vec!["one".into()])
+        );
+        let cases = [
+            ("> [!tip]\n> two", Some(AlertKind::Tip)),
+            ("> [!NOTE]   \n> trailing", Some(AlertKind::Note)),
+            (">   [!TIP]\n> leading", Some(AlertKind::Tip)),
+            ("> [!Warning]\n>\n> after a blank", Some(AlertKind::Warning)),
+            ("> [!WARNING] same line", None),
+            ("> [!IMPORTANT]", None),
+            ("> [!FOO]\n> five", None),
+            ("> text\n> [!NOTE]", None),
+            ("> \\[!NOTE]\n> escaped", Some(AlertKind::Note)),
+            ("> [!NOT&#69;]\n> referenced", Some(AlertKind::Note)),
+            ("> [!NOTE]  \n> hard line", Some(AlertKind::Note)),
+            ("> [!NOTE]\rcarriage", Some(AlertKind::Note)),
+            ("> [!NOTE]\nlazy", Some(AlertKind::Note)),
+            ("> [!NOTE]\u{a0}\n> no-break space", None),
+            ("> **[!TIP]**\n> strong", None),
+            ("> <span>[!WARNING]</span>\n> tag", None),
+            ("[!NOTE]: https://example.com\n\n> [!NOTE]\n> a link", None),
+        ];
+        for (source, kind) in cases {
+            assert_eq!(alert(source).map(|found| found.0), kind, "{source:?}");
+        }
+        let nested = parse("- > [!CAUTION]\n  > in a list");
+        assert!(matches!(&nested[0], Node::List { .. }), "{nested:?}");
+        let blocks = alert("> [!NOTE]\n> # head\n> - item").expect("an alert");
+        assert!(matches!(
+            &blocks.1[..],
+            [Node::Heading(1, _), Node::List { .. }]
+        ));
+        let styled = alert("> [!CAUTION]\n> a **b**\n> c").expect("an alert");
+        let Node::Paragraph(line) = &styled.1[0] else {
+            panic!("a paragraph, not {:?}", styled.1)
+        };
+        let bold = 2..3;
+        assert_eq!(
+            (line.text.as_str(), &line.styles[..]),
+            ("a b c", &[(bold, Style::Strong)][..])
+        );
+    }
+
+    #[test]
+    fn a_toc_paragraph_lists_every_heading() {
+        let nodes = parse("[toc]\n\n# A\n\n> ## B :smile:\n");
+        let Node::Toc(headings) = &nodes[0] else {
+            panic!("a toc, not {nodes:?}")
+        };
+        let listed: Vec<(u8, &str, usize)> = headings
+            .iter()
+            .map(|heading| (heading.depth, heading.title.as_str(), heading.at))
+            .collect();
+        assert_eq!(listed, [(1, "A", 7), (2, "B 😄", 14)]);
+        assert!(matches!(&parse("  [TOC]  ")[0], Node::Toc(_)));
+        assert!(matches!(&parse("[toc] now")[0], Node::Paragraph(_)));
+        assert!(matches!(&parse("> [toc]")[0], Node::Quote(_)));
+    }
+
+    fn html(source: &str) -> Option<Inline> {
+        match parse(source).into_iter().next() {
+            Some(Node::Paragraph(line)) => Some(line),
+            None => None,
+            other => panic!("a paragraph, not {other:?}"),
+        }
+    }
+
+    #[test]
+    fn an_html_block_shows_its_text_as_a_browser_does() {
+        let centered = html(
+            "<div align=\"center\">\n  <b>Bold</b>   and\n  :smile: &amp; <code>:smile:</code>\n</div>",
+        )
+        .expect("text");
+        assert_eq!(centered.text, "Bold and 😄 & :smile:");
+        let (bold, code) = (0..4, 16..23);
+        assert_eq!(
+            centered.styles,
+            [(bold, Style::Strong), (code, Style::Code)]
+        );
+        let parts = html("<p>one <b>two </b></p>\n<p>three &lt;b&gt;</p>").expect("text");
+        assert_eq!(parts.text, "one two\nthree <b>");
+        assert_eq!(
+            html("<div>\na <br> b</br>c</div>").expect("text").text,
+            "a\nb\nc"
+        );
+        let filtered = "<div>\n<script>x</script>\n<!-- note -->\nshown<style>p{}</style>\n</div>";
+        assert_eq!(
+            html(filtered).expect("text").text,
+            "<script>x</script> shown<style>p{}</style>"
+        );
+        let crossed = "<div>before<script>a</scriptx>b</script>after</div>";
+        assert_eq!(
+            html(crossed).expect("text").text,
+            "before<script>ab</script>after"
+        );
+        let split = parse("<div>\n<script>\nfirst\n\nsecond\n</script>\n</div>");
+        assert_eq!(text(&split), ["<script> first", "second </script>"]);
+        let inline = html("a <script>b</script> c").expect("text");
+        assert_eq!(inline.text, "a <script>b</script> c");
+        assert_eq!(html("<div>\na < b <i").expect("text").text, "a < b");
+    }
+
+    #[test]
+    fn a_closing_block_ends_what_opened_inside_it() {
+        let marked = html("<div><mark>x</div>y").expect("text");
+        assert_eq!(
+            (marked.text.as_str(), &marked.styles[..]),
+            ("x\ny", &[(0..1, Style::Mark)][..])
+        );
+        let bold = html("<div><b>x</div>y").expect("text");
+        assert_eq!(bold.styles, [(0..1, Style::Strong), (2..3, Style::Strong)]);
+        let kept = html("<div><mark><p>x</p>y</mark></div>").expect("text");
+        assert_eq!(kept.styles, [(0..3, Style::Mark)]);
+    }
+
+    #[test]
+    fn a_block_start_ends_what_html5_ends() {
+        let mark = [(0..1, Style::Mark)];
+        for source in [
+            "<ul><li><mark>x<li>y</ul>z",
+            "<div><p><mark>x<div>y</div>z</div>",
+            "<dl><dt><mark>x<dd>y</dl>z",
+        ] {
+            let line = html(source).expect("text");
+            assert_eq!(
+                (line.text.as_str(), &line.styles[..]),
+                ("x\ny\nz", &mark[..])
+            );
+        }
+        let kbd = html("<div><p><kbd>x<p>y</div>z").expect("text");
+        assert_eq!(kbd.styles, [(0..1, Style::Code)]);
+        let nested = html("<ul><li><mark>a<ul><li>b</li></ul></li></ul>").expect("text");
+        assert_eq!(
+            nested.styles,
+            [(0..3, Style::Mark)],
+            "a list stops the search"
+        );
+    }
+
+    #[test]
+    fn filtered_tags_are_text_and_names_end_as_html5_ends_them() {
+        // GitHub's answers, `.work/R4.3-fix3/github-*.log`.
+        for (source, shown) in [
+            (
+                "<div><script>:smile:</script> :smile:</div>",
+                "<script>:smile:</script> :smile:",
+            ),
+            (
+                "<div><script><b>:smile:</b></script> :smile:</div>",
+                "<script>😄</script> 😄",
+            ),
+            (
+                "<div><script> :smile:</script> :smile:</div>",
+                "<script> 😄</script> 😄",
+            ),
+            (
+                "<div><script title=\" :smile:\"> x:smile:</div>",
+                "<script title=\" 😄\"> x😄",
+            ),
+            (
+                "<div><iframe title=\":smile:\"> :smile:</div>",
+                "<iframe title=\":smile:\"> :smile:",
+            ),
+            ("<div>\n:smile: x:smile:\n</div>", "😄 x😄"),
+            ("<div>\t:smile: x:smile:</div>", "😄 x😄"),
+            ("<div>a\n :smile: x:smile:</div>", "a 😄 x😄"),
+            ("<div>y\n:smile: x:smile:</div>", "y :smile: x:smile:"),
+            ("<div>:smile:</div>", "😄"),
+        ] {
+            assert_eq!(html(source).expect("text").text, shown, "{source:?}");
+        }
+        let named = "<div>a<script:custom>x</script:custom>b<script!>y</script!>c</div>";
+        assert_eq!(html(named).expect("text").text, "axbyc");
+    }
+
+    #[test]
+    fn every_html5_p_closer_ends_a_p() {
+        for name in ["fieldset", "menu"] {
+            let line = html(&format!("<div><p><mark>x<{name}>y</{name}>z</div>")).expect("text");
+            let mark = [(0..1, Style::Mark)];
+            assert_eq!((line.text.as_str(), &line.styles[..]), ("x\nyz", &mark[..]));
+        }
+    }
+
+    #[test]
+    fn hostile_html_reads_in_linear_time() {
+        let started = web_time::Instant::now();
+        for source in [
+            "<".repeat(1 << 17),
+            "<a".repeat(1 << 16),
+            "<!--".repeat(1 << 16),
+            "<b>".repeat(1 << 16),
+            "<b>".repeat(1 << 15) + &"</i>".repeat(1 << 15),
+            "<script></script>".repeat(1 << 13),
+            "<div>a ".repeat(1 << 16),
+            "<b> ".repeat(1 << 16),
+            "<li><b>x ".repeat(1 << 15),
+            "<p><i>x ".repeat(1 << 15),
+        ] {
+            let block = format!("<div>\n{source}");
+            parse(&block);
+        }
+        let spent = started.elapsed();
+        assert!(spent.as_secs() < 2, "took {spent:?}");
+    }
+}

src/documents/tree/emoji.rs

@@ -0,0 +1,103 @@
+/// `text` with each known `:shortcode:` as its emoji.
+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, '_' | '+' | '-')
+}
+
+/// Where the first `:name:` starts.
+fn candidate(text: &str) -> Option<usize> {
+    let mut from = 0;
+    while let Some(at) = text[from..].find(':').map(|at| from + at) {
+        let after = &text[at + 1..];
+        let len = after
+            .find(|ch: char| !shortcode_char(ch))
+            .unwrap_or(after.len());
+        if len > 0 && after[len..].starts_with(':') {
+            return Some(at);
+        }
+        from = at + 1 + len;
+    }
+    None
+}
+
+/// One DOM text node's shortcodes, as GitHub reads them.
+#[derive(Default)]
+pub(crate) struct Shortcodes {
+    /// Settled by the node's first `:name:`.
+    reads: Option<bool>,
+    /// Text before it held more than white space.
+    inked: bool,
+    last: Option<char>,
+}
+
+impl Shortcodes {
+    /// A new DOM text node starts.
+    pub(crate) fn split(&mut self) {
+        *self = Self::default();
+    }
+
+    /// Blank or spaced text before the first reads them all.
+    pub(crate) fn read(&mut self, text: &str) -> String {
+        if self.reads.is_none() {
+            let at = candidate(text);
+            let lead = &text[..at.unwrap_or(text.len())];
+            self.inked |= !lead.chars().all(|ch| ch.is_ascii_whitespace());
+            self.last = lead.chars().next_back().or(self.last);
+            self.reads = at.map(|_| !self.inked || self.last == Some(' '));
+        }
+        match self.reads {
+            Some(true) => emoji(text),
+            _ => text.to_string(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[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 long_runs_scan_in_linear_time() {
+        let colons = ":zq".repeat(1 << 16);
+        let started = web_time::Instant::now();
+        assert_eq!(emoji(&colons).len(), colons.len());
+        assert_eq!(Shortcodes::default().read(&colons).len(), colons.len());
+        let spent = started.elapsed();
+        assert!(spent.as_secs() < 2, "192 KiB took {spent:?}");
+    }
+}

src/documents/tree/html.rs

@@ -41,6 +41,125 @@ pub(crate) fn reopens(name: &str) -> bool {
     )
 }
 
+/// GFM's tag filter: these tags show as text.
+pub(crate) fn filtered(name: &str) -> bool {
+    matches!(
+        name,
+        "title"
+            | "textarea"
+            | "style"
+            | "xmp"
+            | "iframe"
+            | "noembed"
+            | "noframes"
+            | "script"
+            | "plaintext"
+    )
+}
+
+/// Elements a browser lays as blocks: a line each side.
+pub(crate) fn breaks(name: &str) -> bool {
+    matches!(
+        name,
+        "address"
+            | "article"
+            | "aside"
+            | "blockquote"
+            | "center"
+            | "details"
+            | "div"
+            | "dl"
+            | "dd"
+            | "dt"
+            | "figcaption"
+            | "figure"
+            | "footer"
+            | "h1"
+            | "h2"
+            | "h3"
+            | "h4"
+            | "h5"
+            | "h6"
+            | "header"
+            | "hr"
+            | "li"
+            | "main"
+            | "nav"
+            | "ol"
+            | "p"
+            | "pre"
+            | "section"
+            | "summary"
+            | "table"
+            | "tr"
+            | "ul"
+    )
+}
+
+/// Start tags that end an open `p`, as HTML5 lists them.
+pub(crate) fn closes_p(name: &str) -> bool {
+    matches!(
+        name,
+        "address"
+            | "article"
+            | "aside"
+            | "blockquote"
+            | "center"
+            | "details"
+            | "dialog"
+            | "dir"
+            | "div"
+            | "dl"
+            | "dd"
+            | "dt"
+            | "fieldset"
+            | "figcaption"
+            | "figure"
+            | "footer"
+            | "form"
+            | "h1"
+            | "h2"
+            | "h3"
+            | "h4"
+            | "h5"
+            | "h6"
+            | "header"
+            | "hgroup"
+            | "hr"
+            | "li"
+            | "listing"
+            | "main"
+            | "menu"
+            | "nav"
+            | "ol"
+            | "p"
+            | "pre"
+            | "search"
+            | "section"
+            | "summary"
+            | "table"
+            | "ul"
+    )
+}
+
+/// Bytes through the `>` ending the tag at `html`'s start.
+pub(crate) fn tag_end(html: &str) -> Option<usize> {
+    let (mut quote, mut last) = (None, '<');
+    for (at, ch) in html.char_indices().skip(1) {
+        match quote {
+            Some(open) if ch == open => quote = None,
+            Some(_) => {}
+            None if ch == '>' => return Some(at + 1),
+            None if matches!(ch, '"' | '\'') && last == '=' => quote = Some(ch),
+            None => {}
+        }
+        if !spacing(ch) {
+            last = ch;
+        }
+    }
+    None
+}
+
 /// `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('>')?;
@@ -52,7 +171,7 @@ pub(crate) fn tag(html: &str) -> Option<Tag> {
         return None;
     }
     let named = inner
-        .find(|ch: char| !(ch.is_ascii_alphanumeric() || ch == '-'))
+        .find(|ch: char| spacing(ch) || ch == '/')
         .unwrap_or(inner.len());
     Some(Tag {
         name: inner[..named].to_ascii_lowercase(),
@@ -94,24 +213,29 @@ fn attributes(mut rest: &str) -> Vec<(String, String)> {
                 (&after[..end], &after[end..])
             }
         };
-        out.push((name, decoded(value)));
+        out.push((name, decoded(value, true)));
         rest = left;
     }
 }
 
 /// HTML's whitespace, which is ASCII alone.
-fn spacing(ch: char) -> bool {
+pub(crate) 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 {
+/// Text between tags, references decoded as HTML does.
+pub(crate) fn text(written: &str) -> String {
+    decoded(written, false)
+}
+
+/// References decoded as HTML does, in a value or text.
+fn decoded(text: &str, attribute: bool) -> 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) {
+        match reference(rest, attribute) {
             Some((value, len)) => {
                 out.push_str(&value);
                 rest = &rest[len..];
@@ -129,8 +253,8 @@ fn decoded(text: &str) -> String {
 /// 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)> {
+/// A reference at `text`'s start, as HTML reads it.
+fn reference(text: &str, attribute: bool) -> Option<(String, usize)> {
     let body = text.strip_prefix('&')?;
     if let Some(number) = body.strip_prefix('#') {
         let (digits, radix) = match number.strip_prefix(['x', 'X']) {
@@ -160,8 +284,18 @@ fn attribute_reference(text: &str) -> Option<(String, usize)> {
     {
         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))
+    // Text takes a legacy prefix; a value, the whole name.
+    let shortest = match attribute {
+        true if body[len..].starts_with(['=', ';']) => return None,
+        true => len,
+        false => 1,
+    };
+    let name = (shortest..=len.min(LONGEST))
+        .rev()
+        .map(|end| &name[..end])
+        .find(|name| legacy(name))?;
+    let value = decode_named(name, true).expect("a legacy name");
+    Some((value, name.len() + 1))
 }
 
 /// A name HTML decodes without its semicolon.
@@ -192,39 +326,6 @@ fn numeric(code: Option<u32>) -> char {
     .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] = ['⁰', '¹', '²', '³', '⁴', '⁵', '⁶', '⁷', '⁸', '⁹'];
@@ -297,20 +398,28 @@ mod tests {
 
     #[test]
     fn long_runs_scan_in_linear_time() {
-        let (amps, colons) = ("&".repeat(1 << 18), ":zq".repeat(1 << 16));
+        let amps = "&".repeat(1 << 18);
         let started = web_time::Instant::now();
-        assert_eq!(decoded(&amps).len(), amps.len());
-        assert_eq!(emoji(&colons).len(), colons.len());
+        assert_eq!(decoded(&amps, true).len(), amps.len());
+        assert_eq!(text(&amps).len(), amps.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: 中"), "é 😄 中");
+    fn text_takes_the_longest_legacy_name() {
+        assert_eq!(
+            text("&notit; &amp &ampx &lt3 &nope;"),
+            "¬it; & &x <3 &nope;"
+        );
+        assert_eq!(decoded("&notit;&ampx", true), "&notit;&ampx");
+    }
+
+    #[test]
+    fn a_tag_ends_outside_its_quotes() {
+        assert_eq!(tag_end("<a href=\"x>y\">z"), Some(14));
+        assert_eq!(tag_end("<b it's>r"), Some(8));
+        assert_eq!(tag_end("<b"), None);
     }
 
     #[test]

src/documents/tree/mod.rs

@@ -4,8 +4,12 @@ use markdown::mdast::{self, AlignKind};
 
 use super::markdown::{span, tree, walk};
 
+mod blocks;
+mod emoji;
 mod html;
 
+pub use blocks::{AlertKind, DocumentHeading};
+
 /// How a stretch of inline text prints.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum Style {
@@ -62,6 +66,15 @@ pub enum Node {
         label: String,
         body: Vec<Node>,
     },
+    /// A GitHub alert: a quote under its kind's title.
+    Alert {
+        kind: AlertKind,
+        body: Vec<Node>,
+    },
+    /// `[toc]`: the file's headings.
+    Toc(Vec<DocumentHeading>),
+    /// Front matter, its fences cut.
+    FrontMatter(String),
 }
 
 /// A tree read against its source and its link definitions.
@@ -70,6 +83,7 @@ pub(crate) struct Reader<'a> {
     urls: HashMap<String, String>,
     /// Footnotes numbered by their first reference.
     notes: HashMap<String, usize>,
+    pub headings: Vec<DocumentHeading>,
 }
 
 /// An open element, as HTML names it.
@@ -85,8 +99,14 @@ struct Opened {
 struct Run {
     text: Inline,
     open: Vec<Opened>,
+    /// How many of each name are open.
+    named: HashMap<String, usize>,
     /// Inside an autolink: its text stays as written.
     verbatim: bool,
+    /// The current DOM text node's shortcodes.
+    shortcodes: emoji::Shortcodes,
+    /// White space owed, and the open elements before it.
+    owed: Option<(char, usize)>,
 }
 
 impl Run {
@@ -101,6 +121,34 @@ impl Run {
         done
     }
 
+    fn count(&self, name: &str) -> usize {
+        self.named.get(name).copied().unwrap_or(0)
+    }
+
+    /// Text with its shortcodes read, outside autolinks and `<code>`.
+    fn shown(&mut self, written: &str) -> String {
+        match !self.verbatim && self.count("code") == 0 {
+            true => self.shortcodes.read(written),
+            false => written.to_string(),
+        }
+    }
+
+    /// Text as shown: shortcodes read, lines joined.
+    fn push_text(&mut self, written: &str) {
+        let shown = self.shown(written);
+        self.push_plain(&shown);
+    }
+
+    fn push_plain(&mut self, shown: &str) {
+        let soft = shown.replace("\r\n", " ").replace(['\r', '\n'], " ");
+        self.text.text.push_str(&soft);
+    }
+
+    fn push(&mut self, opened: Opened) {
+        *self.named.entry(opened.name.clone()).or_default() += 1;
+        self.open.push(opened);
+    }
+
     /// The innermost open link's address.
     fn link(&self) -> Option<String> {
         self.open.iter().rev().find_map(|opened| opened.url.clone())
@@ -109,8 +157,12 @@ impl Run {
     /// Opens or closes an element for an inline HTML tag.
     fn html(&mut self, written: &str) {
         let Some(tag) = html::tag(written) else {
-            return;
+            return self.shortcodes.split();
         };
+        if html::filtered(&tag.name) {
+            return self.push_text(&html::text(written));
+        }
+        self.shortcodes.split();
         if tag.name == "br" {
             return self.text.text.push('\n');
         }
@@ -133,7 +185,8 @@ impl Run {
         if name == "a" {
             self.end("a");
         }
-        self.open.push(Opened {
+        self.shortcodes.split();
+        self.push(Opened {
             name: name.to_string(),
             start: self.text.text.len(),
             style,
@@ -143,17 +196,27 @@ impl Run {
 
     /// 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 {
+        if self.count(name) == 0 {
             return;
-        };
+        }
+        self.shortcodes.split();
+        let at = self
+            .open
+            .iter()
+            .rposition(|opened| opened.name == name)
+            .expect("a counted name is open");
         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 let Some((_, from)) = &mut self.owed {
+            *from = (*from).min(at);
+        }
+        let closed = self.open.split_off(at);
+        for opened in &closed {
+            close(&mut self.text, opened, end);
+            *self.named.get_mut(&opened.name).expect("counted") -= 1;
+        }
+        for opened in closed.into_iter().skip(1) {
             if html::reopens(&opened.name) {
-                self.open.push(Opened {
+                self.push(Opened {
                     start: end,
                     ..opened
                 });
@@ -178,11 +241,10 @@ fn close(text: &mut Inline, opened: &Opened, end: usize) {
 /// `markdown` as blocks.
 pub fn parse(markdown: &str) -> Vec<Node> {
     let root = tree(markdown);
-    let mut out = Vec::new();
-    Reader::new(markdown, &root).blocks(
-        root.children().expect("the root holds the blocks"),
-        &mut out,
-    );
+    let (reader, mut out) = (Reader::new(markdown, &root), Vec::new());
+    for node in root.children().expect("the root holds the blocks") {
+        reader.top(node, &mut out);
+    }
     out
 }
 
@@ -191,7 +253,7 @@ 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, mut notes) = (HashMap::new(), HashMap::new());
+        let (mut urls, mut notes, mut headings) = (HashMap::new(), HashMap::new(), Vec::new());
         for node in nodes {
             match node {
                 mdast::Node::Definition(definition) => {
@@ -202,14 +264,25 @@ impl<'a> Reader<'a> {
                     let next = notes.len() + 1;
                     notes.entry(note.identifier.clone()).or_insert(next);
                 }
+                mdast::Node::Heading(heading) => headings.push((heading, span(node).start)),
                 _ => {}
             }
         }
-        Self {
+        let mut reader = Self {
             source,
             urls,
             notes,
-        }
+            headings: Vec::new(),
+        };
+        reader.headings = headings
+            .into_iter()
+            .map(|(heading, at)| DocumentHeading {
+                depth: heading.depth,
+                title: reader.inline(&heading.children).text,
+                at,
+            })
+            .collect();
+        reader
     }
 
     fn blocks(&self, nodes: &[mdast::Node], out: &mut Vec<Node>) {
@@ -293,7 +366,10 @@ impl<'a> Reader<'a> {
                 },
                 body: self.nested(&note.children),
             }),
-            mdast::Node::Html(_) | mdast::Node::Definition(_) => {}
+            mdast::Node::Html(html) => self.html_block(&html.value, out),
+            mdast::Node::Yaml(yaml) => out.push(Node::FrontMatter(yaml.value.clone())),
+            mdast::Node::Toml(toml) => out.push(Node::FrontMatter(toml.value.clone())),
+            mdast::Node::Definition(_) => {}
             other => unreachable!("{other:?} is no block outside MDX"),
         }
     }
@@ -322,17 +398,13 @@ impl<'a> Reader<'a> {
     }
 
     fn inline_into(&self, node: &mdast::Node, run: &mut Run, images: &mut Images) {
+        // Any element ends the DOM text node.
+        if !matches!(node, mdast::Node::Text(_) | mdast::Node::Html(_)) {
+            run.shortcodes.split();
+        }
         let text = &mut run.text;
         let (children, (name, style), url) = match node {
-            mdast::Node::Text(words) => {
-                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::Text(words) => return run.push_text(&words.value),
             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),

src/documents/tree/tests.rs

@@ -362,3 +362,40 @@ fn unknown_tags_show_text_and_only_anchors_link() {
     let urls: Vec<&str> = query.links.iter().map(|(_, url)| url.as_str()).collect();
     assert_eq!(urls, ["https://x.test/?q=1&p=2", "/path/"]);
 }
+
+#[test]
+fn the_first_shortcode_decides_its_text_node() {
+    // GitHub's answers, `.work/R4.3-fix3/github-*.log`.
+    for (source, shown) in [
+        ("a>:smile: :smile:", "a>:smile: :smile:"),
+        ("a> :smile: :smile:", "a> 😄 😄"),
+        ("x:smile: :smile:", "x:smile: :smile:"),
+        ("a;:smile: :smile:", "a;:smile: :smile:"),
+        ("a :smile: b>:smile:", "a 😄 b>😄"),
+        ("a :zzzq: x:smile: :smile:", "a :zzzq: x😄 😄"),
+        ("ax:zzzq: :smile:", "ax:zzzq: :smile:"),
+        ("a :x-y: z:smile:", "a :x-y: z😄"),
+        ("a :x.y: z:smile:", "a :x.y: z:smile:"),
+        ("a.:x.y: :smile:", "a.:x.y: 😄"),
+        ("x\t:smile: y:smile:", "x\t:smile: y:smile:"),
+        ("x\u{a0}:smile: y:smile:", "x\u{a0}:smile: y:smile:"),
+        ("x\n:smile: y:smile:", "x :smile: y:smile:"),
+        ("*x*:smile: :smile:", "x😄 😄"),
+        ("*x*\n:smile: y:smile:", "x 😄 y😄"),
+        ("x:smile: `c` :smile:", "x:smile: c 😄"),
+        ("x:smile:<!-- c --> :smile:", "x:smile: 😄"),
+        ("x:smile:<span>s</span> :smile:", "x:smile:s 😄"),
+        ("x&amp;:smile: :smile:", "x&:smile: :smile:"),
+        ("x:smile:  \n:smile:", "x:smile:\n😄"),
+        (
+            "a <script>x</style>:smile:</script> :smile:",
+            "a <script>x</style>:smile:</script> :smile:",
+        ),
+        (
+            "a <script><b>:smile:</b></script> :smile:",
+            "a <script>😄</script> 😄",
+        ),
+    ] {
+        assert_eq!(line(source).text, shown, "{source:?}");
+    }
+}

src/editor/anchors.rs

@@ -1,6 +1,6 @@
 use std::ops::Range;
 
-use super::state::Marks;
+use super::state::{CodeEditor, Marks};
 
 /// Where `offset` lands after `edits`, sorted and apart, each a replaced range and the length written; none when an edit replaced it.
 fn moved(offset: usize, edits: &[(Range<usize>, usize)]) -> Option<usize> {
@@ -17,6 +17,21 @@ fn moved(offset: usize, edits: &[(Range<usize>, usize)]) -> Option<usize> {
     Some(at as usize)
 }
 
+/// Where the character at `offset` lands; text written at it goes before.
+fn carried(offset: usize, edits: &[(Range<usize>, usize)]) -> Option<usize> {
+    let mut at = offset as isize;
+    for (range, written) in edits {
+        if offset < range.start {
+            break;
+        }
+        if offset < range.end {
+            return None;
+        }
+        at += *written as isize - range.len() as isize;
+    }
+    Some(at as usize)
+}
+
 /// A range through `edits`; none when an edit cut into it.
 fn moved_range(range: &Range<usize>, edits: &[(Range<usize>, usize)]) -> Option<Range<usize>> {
     Some(moved(range.start, edits)?..moved(range.end, edits)?)
@@ -43,6 +58,9 @@ pub(crate) fn shift(marks: &mut Marks, edits: &[(Range<usize>, usize)]) {
         ghost.offset = moved(ghost.offset, edits)?;
         Some(ghost)
     });
+    for anchor in &mut marks.anchors {
+        *anchor = anchor.and_then(|at| carried(at, edits));
+    }
 }
 
 /// Drops the owner's offsets when the whole text changes; they named the old one.
@@ -51,6 +69,27 @@ pub(crate) fn clear(marks: &mut Marks) {
     marks.backgrounds.clear();
     marks.hints.clear();
     marks.ghost = None;
+    marks.anchors.fill(None);
+}
+
+impl CodeEditor {
+    /// Offsets the editor carries through each edit.
+    pub fn set_anchors(&mut self, offsets: impl IntoIterator<Item = usize>) {
+        let text = self.buffer.text();
+        let whole = |at: usize| {
+            let fits = text.is_char_boundary(at);
+            if !fits {
+                log::error!("code editor: anchor {at} splits a character");
+            }
+            fits.then_some(at)
+        };
+        self.marks.anchors = offsets.into_iter().map(whole).collect();
+    }
+
+    /// Where each anchor is now; none once an edit took it.
+    pub fn anchors(&self) -> &[Option<usize>] {
+        &self.marks.anchors
+    }
 }
 
 /// Whether `range` runs forward between whole characters of `text`.
@@ -62,7 +101,7 @@ pub(crate) fn fits(text: &str, range: &Range<usize>) -> bool {
 
 #[cfg(test)]
 mod tests {
-    use super::{fits, moved};
+    use super::{carried, fits, moved};
 
     #[test]
     fn offsets_ride_their_edits() {
@@ -80,4 +119,13 @@ mod tests {
         assert_eq!(moved(8, &edits), Some(10));
         assert!(fits("héllo", &(1..3)) && !fits("héllo", &cut) && !fits("ab", &(1..9)));
     }
+
+    #[test]
+    fn anchors_go_after_text_written_at_them() {
+        let edits = [(2..4, 1), (6..6, 3)];
+        assert_eq!(carried(2, &edits), None, "its character replaced");
+        assert_eq!(carried(4, &edits), Some(3), "just past a replace");
+        assert_eq!(carried(6, &edits), Some(8), "after an insertion at it");
+        assert_eq!(carried(1, &edits), Some(1));
+    }
 }

src/editor/state.rs

@@ -84,6 +84,8 @@ pub(crate) struct Marks {
     pub git: Vec<(usize, GitMark)>,
     pub breakpoints: BTreeSet<usize>,
     pub chat: Option<usize>,
+    /// The owner's offsets; an edit over one drops it.
+    pub anchors: Vec<Option<usize>>,
 }
 
 /// The text and cursors one undo step returns to.

src/primitives/icon.rs

@@ -226,6 +226,7 @@ icons! {
     Merge => "merge",
     MessageSquare => "message-square",
     MessageSquareDiff => "message-square-diff",
+    MessageSquareWarning => "message-square-warning",
     MicOff => "mic-off",
     Mic => "mic",
     Minimize2 => "minimize-2",