rust-lang/mdBook · critical

`{}` unexpected event in html block {event:?}

Error message

`{}` unexpected event in html block {event:?}

What it means

When mdbook-html encounters the start of an HTML block, start_tag drains subsequent pulldown-cmark events until the block ends, accepting only Html, Text, and End(HtmlBlock) events. Any other event inside an html block violates the parser contract and panics with the event shown. This guards against parser-version drift where event grouping changes.

Source

Thrown at crates/mdbook-html/src/html/tree.rs:453

                                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"),

View on GitHub (pinned to dc21064fc2)

Solutions

  1. Match the pulldown-cmark version used by your custom mdbook build to the one mdbook-html expects.
  2. Move problematic markdown constructs out of raw HTML blocks in the offending file shown in the panic.
  3. Check preprocessors for event manipulation inside html blocks and fix them to leave blocks intact.
  4. Reproduce with a minimal chapter and file an issue against mdbook if it occurs with stock tooling.

Example fix

// before (src/page.md) — construct inside raw html block
<div>
*emph inside raw block*
</div>

// after — close the block before markdown
<div>
</div>
*emph outside the block*
Defensive patterns

Strategy: validation

Validate before calling

// reject markdown where raw HTML blocks contain markdown constructs
for block in raw_html_blocks(chapter_content)? {
    if block.contains("*") || block.contains("`") {
        warn!("markdown syntax inside raw HTML block may break rendering: {:?}", block);
    }
}

Try / catch

std::panic::catch_unwind(|| render(book))
    .map_err(|_| anyhow!("html block rendering panicked; check markdown inside raw HTML blocks and parser versions"))?;

Prevention

When it happens

Trigger: While consuming an html block in start_tag, the pulldown-cmark iterator yields an event other than Html/Text/End(HtmlBlock) — e.g. a Start/End of another tag, Code, or FootnoteReference appearing inside a raw HTML block, usually due to a parser version mismatch or a preprocessor rewriting events inside the block.

Common situations: Markdown file whose raw HTML block contains constructs a different parser version splits into extra events; a preprocessor splitting/merging events within html blocks; upgrading pulldown-cmark in a custom build without updating mdbook-html's assumptions.

Related errors

AI-assisted analysis of rust-lang/mdBook@dc21064fc2 (2026-09-01). Data as JSON: /api/errors/603ed0b8ac3e6c96. Report an issue: GitHub.