mdbook/crates/mdbook-html/src/html/tree.rs

//! Tree data structure for representing a markdown document.
//!
//! [`MarkdownTreeBuilder::build`] is the primary entry point of this module.
//! It takes events from [`pulldown_cmark`], and generates a [`Tree`]
//! structure of [`Node`] elements. It also handles all the various
//! transformations that mdbook performs, such as creating header links.

use super::tokenizer::parse_html;
use super::{HtmlRenderOptions, hide_lines, wrap_rust_main};
use crate::utils::{id_from_content, unique_id};
use ego_tree::{NodeId, NodeRef, Tree};
use html5ever::tendril::StrTendril;
use html5ever::tokenizer::{TagKind, Token};
use html5ever::{LocalName, QualName};
use indexmap::IndexMap;
use mdbook_core::config::RustEdition;
use mdbook_core::static_regex;
use pulldown_cmark::{
    Alignment, BlockQuoteKind, CodeBlockKind, CowStr, Event, LinkType, Tag, TagEnd,
};
use std::borrow::Cow;
use std::collections::{HashMap, HashSet};
use std::ops::Deref;
use tracing::{error, warn};

/// Helper to create a [`QualName`].
macro_rules! attr_qual_name {
    ($name:expr) => {
        QualName::new(None, html5ever::ns!(), LocalName::from($name))
    };
}

/// A node in the [`Tree`].
#[derive(Debug)]
pub(crate) enum Node {
    /// An HTML [`Element`].
    Element(Element),
    /// Plain text.
    ///
    /// This will be escaped when serialized.
    Text(StrTendril),
    /// An HTML comment.
    Comment(StrTendril),
    /// Root node of a tree fragment.
    ///
    /// This is a general purpose node whenever it is convenient to have a
    /// container of other nodes.
    Fragment,
    /// Raw data that should be copied into the output as-is without escaping.
    RawData(StrTendril),
}

impl Node {
    /// If this is an [`Element`], return it.
    pub(crate) fn as_element(&self) -> Option<&Element> {
        if let Node::Element(el) = self {
            Some(el)
        } else {
            None
        }
    }

    /// If this is an [`Element`], return it (mutable).
    fn as_element_mut(&mut self) -> Option<&mut Element> {
        if let Node::Element(el) = self {
            Some(el)
        } else {
            None
        }
    }
}

/// An HTML element.
#[derive(Debug)]
pub(crate) struct Element {
    /// The tag name.
    pub(crate) name: QualName,
    /// Element attributes.
    pub(crate) attrs: Attributes,
    /// True if this tag ends with `/>`.
    pub(crate) self_closing: bool,
}

impl Element {
    /// Creates a new HTML element.
    pub(crate) fn new(tag_name: &str) -> Element {
        let name = QualName::new(None, html5ever::ns!(html), LocalName::from(tag_name));
        Element {
            name,
            attrs: Attributes::new(),
            self_closing: false,
        }
    }

    /// The name of this element.
    pub(crate) fn name(&self) -> &str {
        self.name.local.deref()
    }

    /// If this is a heading element, returns the level of the heading.
    #[allow(dead_code, reason = "currently only used in search")]
    pub(crate) fn heading_level(&self) -> Option<u8> {
        let name = self.name();
        if matches!(name, "h1" | "h2" | "h3" | "h4" | "h5" | "h6") {
            Some(name.as_bytes()[1] - b'0')
        } else {
            None
        }
    }

    /// Returns the value of an attribute.
    pub(crate) fn attr(&self, name: &str) -> Option<&str> {
        let qname = attr_qual_name!(name);
        self.attrs.get(&qname).map(Deref::deref)
    }

    /// Inserts an attribute.
    pub(crate) fn insert_attr(&mut self, name: &str, value: StrTendril) {
        let name = attr_qual_name!(name);
        self.attrs.insert(name, value);
    }
}

/// A map of attributes on an [`Element`].
type Attributes = IndexMap<QualName, StrTendril>;

/// Helper to convert [`CowStr`] to a [`StrTendril`].
trait ToTendril {
    /// Converts self to a [`StrTendril`].
    fn into_tendril(self) -> StrTendril;
}

impl ToTendril for CowStr<'_> {
    fn into_tendril(self) -> StrTendril {
        match self {
            CowStr::Boxed(s) => {
                let s: String = s.into();
                StrTendril::from(s)
            }
            CowStr::Borrowed(s) => StrTendril::from(s),
            CowStr::Inlined(s) => StrTendril::from(s.as_ref()),
        }
    }
}

/// Tracks the current state of parsing a table.
///
/// This is used to determine if it should generate `<th>` or `<td>` tags.
enum TableState {
    /// Currently in the table head.
    Head,
    /// Currently in the table body.
    Body,
}

/// A builder used to create a [`Tree`] of [`Node`] elements.
///
/// Parts of this are based on pulldown-cmark's serializer (like table handling).
pub(crate) struct MarkdownTreeBuilder<'opts, 'event, EventIter> {
    /// [`pulldown_cmark`] iterator of [`pulldown_cmark::Event`] elements.
    events: EventIter,
    /// Options for how to generate the HTML.
    options: &'opts HtmlRenderOptions<'opts>,
    /// The tree that is being built.
    tree: Tree<Node>,
    /// The ID of the current [`Node`].
    current_node: NodeId,
    /// The tag stack.
    ///
    /// This is used to set the `current_node` as the parser enters and leaves
    /// a tag.
    tag_stack: Vec<NodeId>,
    /// When parsing a table, whether or not we are currently in the head or
    /// the body.
    table_state: TableState,
    /// When parsing a table, the alignments of the columns.
    ///
    /// The count should match the number of columns.
    table_alignments: Vec<Alignment>,
    /// What parsing a table, the index of the current column.
    table_cell_index: usize,
    /// Mapping of footnote numbers.
    ///
    /// This is used for generating linkbacks in the definitions.
    ///
    /// This is a map of `name -> (number, count)`.
    ///
    /// - `name` is the name of the footnote.
    /// - `number` is the footnote number displayed in the output.
    /// - `count` is the number of references to this footnote (used for multiple
    ///   linkbacks, and checking for unused footnotes).
    footnote_numbers: HashMap<CowStr<'event>, (usize, u32)>,
    /// Footnote definitions.
    ///
    /// This is a map of `name -> NodeId` of each footnote definition. When
    /// parsing footnotes, they are initially left in the position where they
    /// were defined as an `<li>` tag. The [`NodeId`] here is the id of that
    /// tag. After the document has been parsed, all the definitions are moved
    /// to the end of the document.
    footnote_defs: HashMap<CowStr<'event>, NodeId>,
}

impl<'opts, 'event, EventIter> MarkdownTreeBuilder<'opts, 'event, EventIter>
where
    EventIter: Iterator<Item = Event<'event>>,
{
    /// Processes a [`pulldown_cmark`] iterator of [`pulldown_cmark::Event`]
    /// values, and generates a tree of [`Node`] values.
    pub(crate) fn build(options: &'opts HtmlRenderOptions<'opts>, events: EventIter) -> Tree<Node> {
        let tree = Tree::new(Node::Fragment);
        let root = tree.root().id();

        let mut builder = Self {
            events,
            options,
            tree,
            current_node: root,
            tag_stack: vec![root],
            table_state: TableState::Head,
            table_alignments: Vec::new(),
            table_cell_index: 0,
            footnote_numbers: HashMap::new(),
            footnote_defs: HashMap::new(),
        };
        builder.process_events();
        builder.add_header_links();
        builder.update_code_blocks();
        builder.convert_fontawesome();
        builder.tree
    }

    /// Append a new child to the current node.
    ///
    /// Returns the [`NodeId`] of the new node.
    fn append(&mut self, node: Node) -> NodeId {
        self.tree
            .get_mut(self.current_node)
            .unwrap()
            .append(node)
            .id()
    }

    /// Appends text to the current node.
    ///
    /// If the previous sibling is a text node, then it merges with that node.
    /// This makes some processing more convenient.
    fn append_text(&mut self, text: StrTendril) {
        let mut current = self.tree.get_mut(self.current_node).unwrap();
        if let Some(mut prev) = current.last_child()
            && let Node::Text(prev_text) = prev.value()
        {
            prev_text.push_slice(&text);
        } else {
            self.append(Node::Text(text));
        }
    }

    /// Append a new child to the current node, and make the new node the current node.
    ///
    /// This should only be used if you expect `pop` to be called.
    fn push(&mut self, node: Node) {
        let new_node = self.append(node);
        self.tag_stack.push(new_node);
        self.current_node = new_node;
    }

    /// Append a new child to the current node, and make the new node the current node.
    ///
    /// As compared to `push`, it is *not* expected that there will be a `pop` called
    /// for this node. The next call to `pop` will unwind the stack past this node.
    fn push_no_stack(&mut self, node: Node) {
        let new_node = self.append(node);
        self.current_node = new_node;
    }

    /// Switch the current node to the current node's parent.
    fn pop(&mut self) {
        self.tag_stack.pop();
        if let Some(&parent) = self.tag_stack.last() {
            self.current_node = parent;
        } else {
            panic!("pop too far processing `{}`", self.options.path.display());
        }
    }

    /// Returns all of the [`NodeId`]s, filtering out just the [`Element`]
    /// nodes where the given callback returns `true` based on the element
    /// name.
    fn node_ids_for_tag(&self, filter: &dyn Fn(&str) -> bool) -> Vec<NodeId> {
        self.tree
            .nodes()
            .filter(|node| {
                let Node::Element(el) = node.value() else {
                    return false;
                };
                filter(el.name())
            })
            .map(|node| node.id())
            .collect()
    }

    /// The main processing loop. Processes all events until the end.
    fn process_events(&mut self) {
        while let Some(event) = self.events.next() {
            match event {
                Event::Start(tag) => self.start_tag(tag),
                Event::End(tag) => {
                    self.pop();
                    match tag {
                        TagEnd::TableHead => {
                            self.table_state = TableState::Body;
                            self.push(Node::Element(Element::new("tbody")));
                        }
                        TagEnd::TableCell => {
                            self.table_cell_index += 1;
                        }
                        TagEnd::Table => {
                            // Pop tbody or thead
                            self.pop();
                        }
                        _ => {}
                    }
                }
                Event::Text(text) => {
                    self.append_text(text.into_tendril());
                }
                Event::Code(code) => {
                    self.push(Node::Element(Element::new("code")));
                    self.append(Node::Text(code.into_tendril()));
                    self.pop();
                }
                Event::InlineMath(text) => {
                    let mut span = Element::new("span");
                    span.insert_attr("class", "math math-inline".into());
                    self.push(Node::Element(span));
                    self.append(Node::Text(text.into_tendril()));
                    self.pop();
                }
                Event::DisplayMath(text) => {
                    let mut span = Element::new("span");
                    span.insert_attr("class", "math math-display".into());
                    self.push(Node::Element(span));
                    self.append(Node::Text(text.into_tendril()));
                    self.pop();
                }
                Event::Html(html) => {
                    // The loop in Tag::HtmlBlock should have consumed all
                    // Html events.
                    panic!(
                        "`{}` unexpected Html event: {html}",
                        self.options.path.display()
                    );
                }
                Event::InlineHtml(html) => self.append_html(&html),
                Event::FootnoteReference(name) => self.footnote_reference(name),
                Event::SoftBreak => {
                    self.append_text("\n".into());
                }
                Event::HardBreak => {
                    self.append(Node::Element(Element::new("br")));
                }
                Event::Rule => {
                    self.append(Node::Element(Element::new("hr")));
                }
                Event::TaskListMarker(checked) => {
                    let mut input = Element::new("input");
                    input.insert_attr("disabled", "".into());
                    input.insert_attr("type", "checkbox".into());
                    if checked {
                        input.insert_attr("checked", "".into());
                    }
                    self.push(Node::Element(input));
                    // Add some space before whatever follows.
                    self.append(Node::Text(" ".into()));
                    self.pop();
                }
            }
        }
        self.collect_footnote_defs();
    }

    fn start_tag(&mut self, tag: Tag<'event>) {
        let element = match tag {
            Tag::Paragraph => Element::new("p"),
            Tag::Heading {
                level,
                id,
                classes,
                attrs,
            } => {
                let mut el = Element::new(&level.to_string());
                for (name, value) in attrs {
                    let name =
                        QualName::new(None, html5ever::ns!(), LocalName::from(Cow::from(name)));
                    let value = value.unwrap_or_else(|| CowStr::from(""));
                    el.attrs.insert(name, value.into_tendril());
                }
                if let Some(id) = id {
                    el.insert_attr("id", id.into_tendril());
                }
                if !classes.is_empty() {
                    let classes = classes.join(" ");
                    el.insert_attr("class", classes.into());
                }
                el
            }
            Tag::BlockQuote(kind) => {
                let mut b = Element::new("blockquote");
                if let Some(kind) = kind {
                    let class = match kind {
                        BlockQuoteKind::Note => "markdown-alert-note",
                        BlockQuoteKind::Tip => "markdown-alert-tip",
                        BlockQuoteKind::Important => "markdown-alert-important",
                        BlockQuoteKind::Warning => "markdown-alert-warning",
                        BlockQuoteKind::Caution => "markdown-alert-caution",
                    };
                    b.insert_attr("class", class.into());
                }
                b
            }
            Tag::CodeBlock(kind) => {
                let mut code = Element::new("code");
                match kind {
                    CodeBlockKind::Fenced(info) => {
                        let mut infos =
                            info.split([' ', '\t', ',']).filter(|info| !info.is_empty());
                        if let Some(lang) = infos.next() {
                            let mut classes = String::with_capacity(info.len() + 10);
                            // The first element in the infostring is treated as the language.
                            classes.push_str("language-");
                            classes.push_str(lang);
                            // The rest are just added as classes.
                            while let Some(info) = infos.next() {
                                classes.push(' ');
                                classes.push_str(info);
                            }
                            code.insert_attr("class", classes.into());
                        }
                    }
                    CodeBlockKind::Indented => {}
                }
                self.push_no_stack(Node::Element(Element::new("pre")));
                code
            }
            Tag::HtmlBlock => {
                // To process the HTML correctly, this needs to
                // collect it all into a single string.
                let mut html = String::new();
                while let Some(event) = self.events.next() {
                    match event {
                        Event::Html(text) | Event::Text(text) => html.push_str(&text),
                        Event::End(TagEnd::HtmlBlock) => break,
                        _ => panic!(
                            "`{}` unexpected event in html block {event:?}",
                            self.options.path.display()
                        ),
                    }
                }
                self.append_html(&html);
                // TagEnd::HtmlBlock must not pop.
                return;
            }
            Tag::List(Some(start)) => {
                let mut ol = Element::new("ol");
                if start != 1 {
                    ol.insert_attr("start", format!("{start}").into());
                }
                ol
            }
            Tag::List(None) => Element::new("ul"),
            Tag::Item => Element::new("li"),
            Tag::FootnoteDefinition(name) => {
                if self.footnote_defs.contains_key(&name) {
                    warn!(
                        "footnote `{name}` in {} defined multiple times - \
                                     not updating to new definition",
                        self.options.path.display()
                    );
                    self.eat_till_end();
                    return;
                } else {
                    let mut el = Element::new("li");
                    el.insert_attr("id", format!("footnote-{name}").into());
                    self.push(Node::Element(el));
                    self.footnote_defs.insert(name, self.current_node);
                    return;
                }
            }
            Tag::DefinitionList => Element::new("dl"),
            Tag::DefinitionListTitle => Element::new("dt"),
            Tag::DefinitionListDefinition => Element::new("dd"),
            Tag::Table(alignments) => {
                self.table_alignments = alignments.clone();
                // This div wrapper around the table is used to apply
                // `overflow-x: auto` so that wide tables can be scrolled
                // horizontally, rather than overflowing or scrolling the
                // entire page. See
                // https://github.com/rust-lang/mdBook/pull/1617
                let mut div = Element::new("div");
                div.insert_attr("class", "table-wrapper".into());
                self.push_no_stack(Node::Element(div));
                Element::new("table")
            }
            Tag::TableHead => {
                self.table_state = TableState::Head;
                self.table_cell_index = 0;
                let thead = Element::new("thead");
                self.push_no_stack(Node::Element(thead));
                Element::new("tr")
            }
            Tag::TableRow => {
                self.table_cell_index = 0;
                Element::new("tr")
            }
            Tag::TableCell => {
                let mut cell = match self.table_state {
                    TableState::Head => Element::new("th"),
                    TableState::Body => Element::new("td"),
                };
                let style = match self.table_alignments.get(self.table_cell_index) {
                    Some(&Alignment::Left) => "text-align: left",
                    Some(&Alignment::Center) => "text-align: center",
                    Some(&Alignment::Right) => "text-align: right",
                    Some(&Alignment::None) | None => "",
                };
                if !style.is_empty() {
                    cell.insert_attr("style", style.into());
                }
                cell
            }
            Tag::Emphasis => Element::new("em"),
            Tag::Strong => Element::new("strong"),
            Tag::Strikethrough => Element::new("del"),
            Tag::Superscript => Element::new("sup"),
            Tag::Subscript => Element::new("sub"),
            Tag::Link {
                link_type,
                dest_url,
                title,
                id: _,
            } => {
                let href: StrTendril = if matches!(link_type, LinkType::Email) {
                    format!("mailto:{dest_url}").into()
                } else {
                    fix_link(dest_url).into_tendril()
                };
                let mut a = Element::new("a");
                a.insert_attr("href", href);
                if !title.is_empty() {
                    a.insert_attr("title", title.into_tendril());
                }
                a
            }
            Tag::Image {
                link_type: _,
                dest_url,
                title,
                id: _,
            } => {
                let mut img = Element::new("img");
                let src = fix_link(dest_url).into_tendril();
                img.insert_attr("src", src);
                if !title.is_empty() {
                    img.insert_attr("title", title.into_tendril());
                }
                // This will eat TagEnd::Image
                let alt = self.text_for_img_alt();
                img.insert_attr("alt", alt.into());
                self.append(Node::Element(img));
                return;
            }
            Tag::MetadataBlock(_) => {
                // Eat all events till the end of MetadataBlock.
                while let Some(event) = self.events.next() {
                    if matches!(event, Event::End(TagEnd::MetadataBlock(_))) {
                        break;
                    }
                }
                return;
            }
        };
        self.push(Node::Element(element));
    }

    /// Given some HTML, parse it into [`Node`] elements and append them to
    /// the current node.
    fn append_html(&mut self, html: &str) {
        let tokens = parse_html(&html);
        let mut is_raw = false;
        for token in tokens {
            match token {
                Token::DoctypeToken(_) => {}
                Token::TagToken(tag) => {
                    match tag.kind {
                        TagKind::StartTag => {
                            let is_closed = is_void_element(&tag.name) || tag.self_closing;
                            is_raw = matches!(&*tag.name, "script" | "style");
                            let name = QualName::new(None, html5ever::ns!(html), tag.name);
                            let attrs = tag
                                .attrs
                                .into_iter()
                                .map(|attr| (attr.name, attr.value))
                                .collect();
                            let mut el = Element {
                                name,
                                attrs,
                                self_closing: tag.self_closing,
                            };
                            fix_html_link(&mut el);
                            self.push(Node::Element(el));
                            if is_closed {
                                // No end element.
                                self.pop();
                            }
                        }
                        TagKind::EndTag => {
                            is_raw = false;
                            if self.is_html_tag_matching(&tag.name) {
                                self.pop();
                            }
                            // else the stack is corrupt. I'm not really sure
                            // what to do here...
                        }
                    }
                }
                Token::CommentToken(comment) => {
                    self.append(Node::Comment(comment));
                }
                Token::CharacterTokens(chars) => {
                    if is_raw {
                        self.append(Node::RawData(chars));
                    } else {
                        self.append_text(chars);
                    }
                }
                Token::NullCharacterToken => {}
                Token::EOFToken => {}
                Token::ParseError(error) => {
                    warn!(
                        "html parse error in `{}`: {error}\n\
                         Html text was:\n\
                         {html}",
                        self.options.path.display()
                    );
                }
            }
        }
    }

    /// This is used to verify HTML parsing keeps the stack of tags in sync.
    fn is_html_tag_matching(&self, name: &str) -> bool {
        let current = self.tree.get(self.current_node).unwrap().value();
        if let Node::Element(el) = current
            && el.name() == name
        {
            return true;
        }
        error!(
            "internal error: HTML tag stack out of sync.\n
             path: `{}`\n\
             current={current:?}\n\
             pop name: {name}",
            self.options.path.display()
        );
        false
    }

    /// Eats all pulldown-cmark events until the next `End` matching the
    /// current nesting level.
    fn eat_till_end(&mut self) {
        let mut nest = 0;
        while let Some(event) = self.events.next() {
            match event {
                Event::Start(_) => nest += 1,
                Event::End(_) => {
                    if nest == 0 {
                        break;
                    }
                    nest -= 1;
                }
                _ => {}
            }
        }
    }

    /// Eats events generating a plain text string, stripping out any
    /// formatting elements.
    fn text_for_img_alt(&mut self) -> String {
        let mut nest = 0;
        let mut output = String::new();
        while let Some(event) = self.events.next() {
            match event {
                Event::Start(_) => nest += 1,
                Event::End(_) => {
                    if nest == 0 {
                        break;
                    }
                    nest -= 1;
                }
                Event::Html(_) => {}
                Event::InlineHtml(text) | Event::Code(text) | Event::Text(text) => {
                    output.push_str(&text);
                }
                Event::InlineMath(text) => {
                    output.push('$');
                    output.push_str(&text);
                    output.push('$');
                }
                Event::DisplayMath(text) => {
                    output.push_str("$$");
                    output.push_str(&text);
                    output.push_str("$$");
                }
                Event::SoftBreak | Event::HardBreak | Event::Rule => output.push(' '),
                Event::FootnoteReference(_) => {}
                Event::TaskListMarker(_) => {}
            }
        }
        output
    }

    /// Appends a new footnote reference.
    fn footnote_reference(&mut self, name: CowStr<'event>) {
        let len = self.footnote_numbers.len() + 1;
        let (n, count) = self
            .footnote_numbers
            .entry(name.clone())
            .or_insert((len, 0));
        *count += 1;
        let (n, count) = (*n, *count);

        let current = self.tree.get(self.current_node).unwrap();
        if let Some(last) = current.last_child()
            && let Node::Element(el) = last.value()
        {
            if el.attr("class") == Some("footnote-reference") {
                self.append(Node::Text(" ".into()));
            }
        }
        let mut sup = Element::new("sup");
        sup.insert_attr("class", "footnote-reference".into());
        let id = format!("fr-{name}-{count}");
        sup.insert_attr("id", id.into());
        self.push(Node::Element(sup));
        let mut a = Element::new("a");
        a.insert_attr("href", format!("#footnote-{name}").into());
        self.push(Node::Element(a));
        self.append(Node::Text(format!("{n}").into()));
        self.pop(); // a
        self.pop(); // sup
    }

    /// This is used after parsing is complete to move the footnote
    /// definitions to the end of the document.
    fn collect_footnote_defs(&mut self) {
        if self.footnote_defs.is_empty() {
            return;
        }
        let defs = std::mem::take(&mut self.footnote_defs);
        let mut defs: Vec<_> = defs.into_iter().collect();
        // Detach nodes and remove unused.
        defs.retain(|(name, def_id)| {
            let mut node = self.tree.get_mut(*def_id).unwrap();
            node.detach();

            if !self.footnote_numbers.contains_key(name) {
                warn!(
                    "footnote `{name}` in `{}` is defined but not referenced",
                    self.options.path.display()
                );
                false
            } else {
                true
            }
        });
        defs.sort_by_cached_key(|(name, _)| self.footnote_numbers[name].0);

        // Move defs to the end of the chapter.
        self.append(Node::Element(Element::new("hr")));
        let mut ol = Element::new("ol");
        ol.insert_attr("class", "footnote-definition".into());
        let ol_id = self.append(Node::Element(ol));
        for (name, def_id) in defs {
            // Generate the linkbacks.
            let count = self.footnote_numbers[&name].1;
            for usage in 1..=count {
                let nth = if usage == 1 {
                    String::new()
                } else {
                    usage.to_string()
                };
                let space = self.tree.orphan(Node::Text(" ".into())).id();
                let mut backlink = Element::new("a");
                backlink.insert_attr("href", format!("#fr-{name}-{usage}").into());
                let mut backlink = self.tree.orphan(Node::Element(backlink));
                backlink.append(Node::Text(format!("↩{nth}").into()));
                let backlink = backlink.id();
                let mut def = self.tree.get_mut(def_id).unwrap();
                if let Some(mut last_child) = def.last_child()
                    && let value = last_child.value()
                    && let Node::Element(last_el) = value
                    && last_el.name() == "p"
                {
                    // Put the linkback at the end of the last paragraph instead
                    // of on a line by itself.
                    last_child.append_id(space);
                    last_child.append_id(backlink);
                } else {
                    // Not a clear place to put it in this circumstance, so put it
                    // at the end.
                    def.append_id(space);
                    def.append_id(backlink);
                };
            }
            let mut ol = self.tree.get_mut(ol_id).unwrap();
            ol.append_id(def_id);
        }
    }

    /// This is used after parsing is complete to add a unique `id` attribute
    /// to all header elements, and to also add an `<a>` tag so that clicking
    /// the header will set the current URL to that header's fragment.
    fn add_header_links(&mut self) {
        let mut id_counter = HashSet::new();
        let headings =
            self.node_ids_for_tag(&|name| matches!(name, "h1" | "h2" | "h3" | "h4" | "h5" | "h6"));
        for heading in headings {
            let node = self.tree.get(heading).unwrap();
            let el = node.value().as_element().unwrap();
            let href = if let Some(id) = el.attr("id") {
                format!("#{id}")
            } else {
                let mut id = String::new();
                let node_id = node.id();
                let node_ref = self.tree.get(node_id).unwrap();
                text_in_node(node_ref, &mut id);
                let id = id_from_content(&id);
                let id = unique_id(&id, &mut id_counter);
                let mut node = self.tree.get_mut(heading).unwrap();
                let el = node.value().as_element_mut().unwrap();
                let href = format!("#{id}");
                el.insert_attr("id", id.into());
                href
            };
            // Insert an <a> element between the heading and its children.
            let mut a = Element::new("a");
            a.insert_attr("class", "header".into());
            a.insert_attr("href", href.into());
            let mut a = self.tree.orphan(Node::Element(a));
            a.reparent_from_id_append(heading);
            let a_id = a.id();
            let mut node = self.tree.get_mut(heading).unwrap();
            node.append_id(a_id);
        }
    }

    /// This is used after parsing is complete to set the appropriate classes
    /// on a code block, to wrap hidden lines in `<span>` tags, and to add an
    /// `fn main() {}` wrapper for Rust code blocks.
    fn update_code_blocks(&mut self) {
        let mut code_ids = self.node_ids_for_tag(&|name| name == "code");
        // The processing below assumes the code block is in a contiguous
        // chunk. The text nodes should have been merged during event
        // processing. I don't know exactly what this should do if it
        // encounters code blocks with non-text nodes.
        code_ids.retain(|id| {
            let code = self.tree.get(*id).unwrap();
            code.children().count() == 1
        });

        for code_id in code_ids.iter().copied() {
            let mut node = self.tree.get_mut(code_id).unwrap();
            let parent_id = node.parent().unwrap().id();
            let code_el = node.value().as_element_mut().unwrap();
            let class = code_el.attr("class").unwrap_or_default();
            let class_set: HashSet<_> = class.split(' ').collect();
            let is_editable = class_set.contains("editable");
            let is_playground = class_set.contains("language-rust")
                && ((!class_set.contains("ignore")
                    && !class_set.contains("noplayground")
                    && !class_set.contains("noplaypen")
                    && self.options.config.playground.runnable)
                    || class_set.contains("mdbook-runnable"));
            if !is_playground {
                continue;
            }
            let add_edition = if class_set.iter().any(|cls| cls.starts_with("edition")) {
                None
            } else {
                self.options.edition.map(|edition| match edition {
                    RustEdition::E2015 => "edition2015",
                    RustEdition::E2018 => "edition2018",
                    RustEdition::E2021 => "edition2021",
                    RustEdition::E2024 => "edition2024",
                    _ => panic!("edition {edition:?} not covered"),
                })
            };
            if let Some(edition) = add_edition {
                code_el.insert_attr("class", format!("{class} {edition}").into());
            }

            let mut node = self.tree.get_mut(code_id).unwrap();
            if !self.options.config.playground.editable || !is_editable {
                if let Some(mut child) = node.first_child()
                    && let Node::Text(text) = child.value()
                {
                    if let Some(new_text) = wrap_rust_main(text) {
                        *text = new_text.into();
                    }
                }
            }

            let mut pre = self.tree.get_mut(parent_id).unwrap();
            let pre = pre.value().as_element_mut().unwrap();
            assert_eq!(pre.name(), "pre");
            pre.insert_attr("class", "playground".into());
        }

        for code_id in code_ids {
            hide_lines(&mut self.tree, code_id, &self.options.config.code.hidelines);
        }
    }

    /// This is used after parsing is complete to replace `<i>` tags with a
    /// `<span>` that includes the corresponding SVG code.
    fn convert_fontawesome(&mut self) {
        use font_awesome_as_a_crate as fa;

        let is = self.node_ids_for_tag(&|name| name == "i");
        for i_id in is {
            let mut icon = String::new();
            let mut type_ = fa::Type::Regular;
            let mut new_classes = String::from("fa-svg");

            let mut node = self.tree.get_mut(i_id).unwrap();
            if node.first_child().is_some() {
                // Just to be safe, only translate <i></i>.
                continue;
            }
            let i_el = node.value().as_element().unwrap();
            let classes = i_el.attr("class").unwrap_or_default();
            for class in classes.split(" ") {
                if let Some(class) = class.strip_prefix("fa-") {
                    icon = class.to_owned();
                } else if class == "fa" {
                    type_ = fa::Type::Regular;
                } else if class == "fas" {
                    type_ = fa::Type::Solid;
                } else if class == "fab" {
                    type_ = fa::Type::Brands;
                } else {
                    new_classes += " ";
                    new_classes += class;
                }
            }

            if !icon.is_empty()
                && let Ok(svg) = fa::svg(type_, &icon)
            {
                let mut span = Element::new("span");
                span.insert_attr("class", new_classes.into());
                for (name, value) in &i_el.attrs {
                    if *name != attr_qual_name!("class") {
                        span.attrs.insert(name.clone(), value.clone());
                    }
                }
                *node.value() = Node::Element(span);
                node.append(Node::RawData(svg.into()));
            }
        }
    }
}

/// Traverse the given node, emitting any plain text into the output.
///
/// This is used to generate the `id` of a header.
fn text_in_node(node: NodeRef<'_, Node>, output: &mut String) {
    for child in node.children() {
        match child.value() {
            Node::Element(_) => {}
            Node::Text(text) => output.push_str(text),
            Node::Comment(_) => {}
            Node::Fragment => {}
            Node::RawData(_) => {}
        }
        text_in_node(child, output);
    }
}

/// Modifies links to work with HTML.
///
/// For local paths, this changes the `.md` extension to `.html`.
fn fix_link<'a>(link: CowStr<'a>) -> CowStr<'a> {
    static_regex!(SCHEME_LINK, r"^[a-z][a-z0-9+.-]*:");
    static_regex!(MD_LINK, r"(?P<link>.*)\.md(?P<anchor>#.*)?");

    if link.starts_with('#') {
        // Fragment-only link.
        return link;
    }
    // Don't modify links with schemes like `https`.
    if SCHEME_LINK.is_match(&link) {
        return link;
    }

    // This is a relative link, adjust it as necessary.
    if let Some(caps) = MD_LINK.captures(&link) {
        let mut fixed_link = String::from(&caps["link"]);
        fixed_link.push_str(".html");
        if let Some(anchor) = caps.name("anchor") {
            fixed_link.push_str(anchor.as_str());
        }
        CowStr::from(fixed_link)
    } else {
        link
    }
}

/// Calls [`fix_link`] for HTML elements.
fn fix_html_link(el: &mut Element) {
    if el.name() != "a" {
        return;
    }
    for attr in ["href", "xlink:href"] {
        if let Some(value) = el.attr(attr) {
            let fixed = fix_link(value.into());
            el.insert_attr(attr, fixed.into_tendril());
        }
    }
}

/// Whether or not this element name is a [void element].
///
/// This is used to know whether or not to expect a `</>` end tag.
///
/// [void element]: https://developer.mozilla.org/en-US/docs/Glossary/Void_element
pub(crate) fn is_void_element(name: &str) -> bool {
    matches!(
        name,
        "area"
            | "base"
            | "br"
            | "col"
            | "embed"
            | "hr"
            | "img"
            | "input"
            | "link"
            | "meta"
            | "param"
            | "source"
            | "track"
            | "wbr"
    )
}