MdBook Warnings: Using Includes Within Admonitions

When working with mdBook, a popular tool for creating online books and documentation, you might encounter warnings related to the use of includes within admonitions. This article delves into a specific scenario where warnings arise due to the interaction between HTML tags, includes, and admonition blocks in mdBook, offering insights and potential solutions. We will explore the issue, its context, and how to address it effectively.

The Problem: Unclosed HTML Tags and Unexpected End Tags

In mdBook 0.5.0, a particular issue arises when using the #include directive within an admonition block. Admonitions are styled blocks that draw attention to specific pieces of content, such as tips, notes, or warnings. The problem manifests when HTML tags, specifically <details> and </details>, are used in conjunction with the #include directive within these admonition blocks. The core issue is that mdBook sometimes incorrectly flags these HTML tags as unclosed or unexpected, even when they are properly balanced. This leads to warning messages during the build process, such as:

WARN unclosed HTML tag `<details>` found in `your_file.md` while exiting BlockQuote(Some(Tip))
HTML tags must be closed before exiting a markdown element.
WARN unexpected HTML end tag `</details>` found in `your_file.md`
Check that the HTML tags are properly balanced.

These warnings indicate that mdBook's parser is having trouble correctly interpreting the HTML structure within the admonition, especially when the content is being included from an external file. This issue can be puzzling because the rendered output often appears correct, even though the warnings are present. The root cause lies in how mdBook processes the markdown and HTML in combination, particularly when includes are involved.

A Detailed Look at the Scenario

Consider a scenario where you want to include a collapsible section within a tip admonition. You might use the <details> and <summary> HTML tags to create this collapsible section. The content for this section, perhaps a table or a code snippet, is stored in a separate HTML file (e.g., assets/tables/any_exp.html). Your markdown might look something like this:

> [!TIP]
> <details><summary>Click to open</summary>{{#include assets/tables/any_exp.html}}</details>

In this example, the #include directive pulls the content from assets/tables/any_exp.html and inserts it into the <details> block. While this renders correctly in the final output, mdBook may still generate warnings about unclosed or unexpected HTML tags. This discrepancy between the rendered output and the warnings highlights the underlying parsing issue.

Why Does This Happen?

The warnings occur due to the way mdBook's markdown parser interacts with HTML and includes. When the parser encounters the #include directive, it essentially inserts the raw content of the included file into the markdown stream. However, the parser might not correctly track the opening and closing of HTML tags across the include boundary. In other words, it might see an opening <details> tag but fail to recognize the corresponding </details> tag after the included content, or vice versa. This leads to the