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] 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 9c94a5b1..5a0786ea 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 f08b5ec8..609fb3c7 100644
--- a/tests/testsuite/markdown/basic_markdown/expected/html.html
+++ b/tests/testsuite/markdown/basic_markdown/expected/html.html
@@ -64,6 +64,6 @@ const x = 'some *text* inside';
 .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 7a75abf1..50263db9 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 @@
 <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 7a75abf1..50263db9 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 @@
 <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>