From ab8a4dfa5aa970d093b0c4c28fc12f52cd4fcd39 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Thu, 30 Oct 2025 10:02:27 -0700
Subject: [PATCH 1/3] Add a test for definition lists with manual HTML tags

---
 tests/testsuite/markdown.rs                      |  4 ++++
 .../expected/html_definition_lists.html          | 16 ++++++++++++++++
 .../expected_disabled/html_definition_lists.html | 16 ++++++++++++++++
 .../markdown/definition_lists/src/SUMMARY.md     |  1 +
 .../src/html_definition_lists.md                 | 10 ++++++++++
 5 files changed, 47 insertions(+)
 create mode 100644 tests/testsuite/markdown/definition_lists/expected/html_definition_lists.html
 create mode 100644 tests/testsuite/markdown/definition_lists/expected_disabled/html_definition_lists.html
 create mode 100644 tests/testsuite/markdown/definition_lists/src/html_definition_lists.md

diff --git a/tests/testsuite/markdown.rs b/tests/testsuite/markdown.rs
index 98fde906ce..7e46ffa228 100644
--- a/tests/testsuite/markdown.rs
+++ b/tests/testsuite/markdown.rs
@@ -157,6 +157,10 @@ fn definition_lists() {
         .check_main_file(
             "book/definition_lists.html",
             file!["markdown/definition_lists/expected_disabled/definition_lists.html"],
+        )
+        .check_main_file(
+            "book/html_definition_lists.html",
+            file!["markdown/definition_lists/expected_disabled/html_definition_lists.html"],
         );
 }
 
diff --git a/tests/testsuite/markdown/definition_lists/expected/html_definition_lists.html b/tests/testsuite/markdown/definition_lists/expected/html_definition_lists.html
new file mode 100644
index 0000000000..7a75abf13c
--- /dev/null
+++ b/tests/testsuite/markdown/definition_lists/expected/html_definition_lists.html
@@ -0,0 +1,16 @@
+<h1 id="html-definition-lists"><a class="header" href="#html-definition-lists">HTML definition lists</a></h1>
+<p>Test for definition lists manually written in HTML.</p>
+<dl>
+    
+<dt id="some-tag"><a class="header" href="#some-tag">Some tag</a></dt>
+
+    
+<dd>Some defintion</dd>
+
+    
+<dt class="myclass" id="myid"><a class="header" href="#myid"><a class="option-anchor" href="#foo">Another definition</a></a></dt>
+
+    
+<dd class="def-class">A definition.</dd>
+
+</dl>
\ No newline at end of file
diff --git a/tests/testsuite/markdown/definition_lists/expected_disabled/html_definition_lists.html b/tests/testsuite/markdown/definition_lists/expected_disabled/html_definition_lists.html
new file mode 100644
index 0000000000..7a75abf13c
--- /dev/null
+++ b/tests/testsuite/markdown/definition_lists/expected_disabled/html_definition_lists.html
@@ -0,0 +1,16 @@
+<h1 id="html-definition-lists"><a class="header" href="#html-definition-lists">HTML definition lists</a></h1>
+<p>Test for definition lists manually written in HTML.</p>
+<dl>
+    
+<dt id="some-tag"><a class="header" href="#some-tag">Some tag</a></dt>
+
+    
+<dd>Some defintion</dd>
+
+    
+<dt class="myclass" id="myid"><a class="header" href="#myid"><a class="option-anchor" href="#foo">Another definition</a></a></dt>
+
+    
+<dd class="def-class">A definition.</dd>
+
+</dl>
\ No newline at end of file
diff --git a/tests/testsuite/markdown/definition_lists/src/SUMMARY.md b/tests/testsuite/markdown/definition_lists/src/SUMMARY.md
index 941e800019..0a93961daf 100644
--- a/tests/testsuite/markdown/definition_lists/src/SUMMARY.md
+++ b/tests/testsuite/markdown/definition_lists/src/SUMMARY.md
@@ -1,3 +1,4 @@
 # Summary
 
 - [Definition lists](./definition_lists.md)
+- [HTML definition lists](./html_definition_lists.md)
diff --git a/tests/testsuite/markdown/definition_lists/src/html_definition_lists.md b/tests/testsuite/markdown/definition_lists/src/html_definition_lists.md
new file mode 100644
index 0000000000..84de694c89
--- /dev/null
+++ b/tests/testsuite/markdown/definition_lists/src/html_definition_lists.md
@@ -0,0 +1,10 @@
+# HTML definition lists
+
+Test for definition lists manually written in HTML.
+
+<dl>
+    <dt>Some tag</dt>
+    <dd>Some defintion</dd>
+    <dt class="myclass" id="myid"><a class="option-anchor" href="#foo">Another definition</a></dt>
+    <dd class="def-class">A definition.</dd>
+</dl>

From 07ed00e8f70dc3669defb9ff62e64d0fd30c53ff Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Thu, 30 Oct 2025 11:40:46 -0700
Subject: [PATCH 2/3] Add a test for manually written header tags

---
 tests/testsuite/markdown/basic_markdown/expected/html.html | 6 +++++-
 tests/testsuite/markdown/basic_markdown/src/html.md        | 6 ++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/tests/testsuite/markdown/basic_markdown/expected/html.html b/tests/testsuite/markdown/basic_markdown/expected/html.html
index 7213939f8b..f08b5ec811 100644
--- a/tests/testsuite/markdown/basic_markdown/expected/html.html
+++ b/tests/testsuite/markdown/basic_markdown/expected/html.html
@@ -62,4 +62,8 @@ <h2 id="style"><a class="header" href="#style">Style</a></h2>
 </style>
 <style media="(width &lt; 500px)">
 .bar { background-color: green }
-</style>
\ No newline at end of file
+</style>
+<h2 id="manual-headers"><a class="header" href="#manual-headers">Manual headers</a></h2>
+<h2 id="my header"><a class="header" href="#my header"><a href="#foo">My Header</a></a></h2>
+
+<h3 id="another-header"><a class="header" href="#another-header">Another header</a></h3>
\ No newline at end of file
diff --git a/tests/testsuite/markdown/basic_markdown/src/html.md b/tests/testsuite/markdown/basic_markdown/src/html.md
index b2383cb452..7e33aaca0b 100644
--- a/tests/testsuite/markdown/basic_markdown/src/html.md
+++ b/tests/testsuite/markdown/basic_markdown/src/html.md
@@ -92,3 +92,9 @@ const x = 'some *text* inside';
 <style media="(width < 500px)">
 .bar { background-color: green }
 </style>
+
+## Manual headers
+
+<h2 id="my header"><a href="#foo">My Header</a></h2>
+
+<h3>Another header</h3>

From 54175698d533c30ea062730f98370fa1e7efd613 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Thu, 30 Oct 2025 11:47:43 -0700
Subject: [PATCH 3/3] Don't modify headers or dt if the tag is manually written
 HTML

This changes it so that header and `<dt>` tags manually written as HTML
are not modified (no anchor, no id, etc.). This is to avoid mangling any
HTML that the user explicitly crafted.

I'm not sure what the fallout from the headers might be, since I'm not
100% sure there aren't uses where the user wanted mdbook to modify
manual HTML. However, I don't see any in rust-lang's use.
---
 crates/mdbook-html/src/html/tree.rs                      | 9 +++++++++
 .../testsuite/markdown/basic_markdown/expected/html.html | 4 ++--
 .../definition_lists/expected/html_definition_lists.html | 4 ++--
 .../expected_disabled/html_definition_lists.html         | 4 ++--
 4 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/crates/mdbook-html/src/html/tree.rs b/crates/mdbook-html/src/html/tree.rs
index 9c94a5b1f2..5a0786ea38 100644
--- a/crates/mdbook-html/src/html/tree.rs
+++ b/crates/mdbook-html/src/html/tree.rs
@@ -77,6 +77,8 @@ pub(crate) struct Element {
     pub(crate) attrs: Attributes,
     /// True if this tag ends with `/>`.
     pub(crate) self_closing: bool,
+    /// True if this was raw HTML written in the markdown.
+    pub(crate) was_raw: bool,
 }
 
 impl Element {
@@ -87,6 +89,7 @@ impl Element {
             name,
             attrs: Attributes::new(),
             self_closing: false,
+            was_raw: false,
         }
     }
 
@@ -618,6 +621,7 @@ where
                                 name,
                                 attrs,
                                 self_closing: tag.self_closing,
+                                was_raw: true,
                             };
                             fix_html_link(&mut el);
                             self.push(Node::Element(el));
@@ -842,6 +846,11 @@ where
         for heading in headings {
             let node = self.tree.get(heading).unwrap();
             let el = node.value().as_element().unwrap();
+            // Don't modify tags if they were manually written HTML. The
+            // user probably had some intent, and we don't want to mess it up.
+            if el.was_raw {
+                continue;
+            }
             let href = if let Some(id) = el.attr("id") {
                 format!("#{id}")
             } else {
diff --git a/tests/testsuite/markdown/basic_markdown/expected/html.html b/tests/testsuite/markdown/basic_markdown/expected/html.html
index f08b5ec811..609fb3c717 100644
--- a/tests/testsuite/markdown/basic_markdown/expected/html.html
+++ b/tests/testsuite/markdown/basic_markdown/expected/html.html
@@ -64,6 +64,6 @@ <h2 id="style"><a class="header" href="#style">Style</a></h2>
 .bar { background-color: green }
 </style>
 <h2 id="manual-headers"><a class="header" href="#manual-headers">Manual headers</a></h2>
-<h2 id="my header"><a class="header" href="#my header"><a href="#foo">My Header</a></a></h2>
+<h2 id="my header"><a href="#foo">My Header</a></h2>
 
-<h3 id="another-header"><a class="header" href="#another-header">Another header</a></h3>
\ No newline at end of file
+<h3>Another header</h3>
\ No newline at end of file
diff --git a/tests/testsuite/markdown/definition_lists/expected/html_definition_lists.html b/tests/testsuite/markdown/definition_lists/expected/html_definition_lists.html
index 7a75abf13c..50263db92c 100644
--- a/tests/testsuite/markdown/definition_lists/expected/html_definition_lists.html
+++ b/tests/testsuite/markdown/definition_lists/expected/html_definition_lists.html
@@ -2,13 +2,13 @@ <h1 id="html-definition-lists"><a class="header" href="#html-definition-lists">H
 <p>Test for definition lists manually written in HTML.</p>
 <dl>
     
-<dt id="some-tag"><a class="header" href="#some-tag">Some tag</a></dt>
+<dt>Some tag</dt>
 
     
 <dd>Some defintion</dd>
 
     
-<dt class="myclass" id="myid"><a class="header" href="#myid"><a class="option-anchor" href="#foo">Another definition</a></a></dt>
+<dt class="myclass" id="myid"><a class="option-anchor" href="#foo">Another definition</a></dt>
 
     
 <dd class="def-class">A definition.</dd>
diff --git a/tests/testsuite/markdown/definition_lists/expected_disabled/html_definition_lists.html b/tests/testsuite/markdown/definition_lists/expected_disabled/html_definition_lists.html
index 7a75abf13c..50263db92c 100644
--- a/tests/testsuite/markdown/definition_lists/expected_disabled/html_definition_lists.html
+++ b/tests/testsuite/markdown/definition_lists/expected_disabled/html_definition_lists.html
@@ -2,13 +2,13 @@ <h1 id="html-definition-lists"><a class="header" href="#html-definition-lists">H
 <p>Test for definition lists manually written in HTML.</p>
 <dl>
     
-<dt id="some-tag"><a class="header" href="#some-tag">Some tag</a></dt>
+<dt>Some tag</dt>
 
     
 <dd>Some defintion</dd>
 
     
-<dt class="myclass" id="myid"><a class="header" href="#myid"><a class="option-anchor" href="#foo">Another definition</a></a></dt>
+<dt class="myclass" id="myid"><a class="option-anchor" href="#foo">Another definition</a></dt>
 
     
 <dd class="def-class">A definition.</dd>