From 051fc9f01db3ae776c1d8e251d0321961a967b72 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 4 Nov 2025 16:04:14 -0800 Subject: [PATCH] Add a comment about the intent of HTML id generation --- crates/mdbook-html/src/utils.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/crates/mdbook-html/src/utils.rs b/crates/mdbook-html/src/utils.rs index b5bc2d7c..68f42a40 100644 --- a/crates/mdbook-html/src/utils.rs +++ b/crates/mdbook-html/src/utils.rs @@ -74,6 +74,15 @@ pub(crate) fn unique_id(id: &str, used: &mut HashSet) -> String { /// Generates an HTML id from the given text. pub(crate) fn id_from_content(content: &str) -> String { + // This is intended to be close to how header ID generation is done in + // other sites and tools, but is not 100% the same. Not all sites and + // tools use the same algorithm. See these for more information: + // + // - https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links + // - https://docs.gitlab.com/user/markdown/#heading-ids-and-links + // - https://pandoc.org/MANUAL.html#extension-auto_identifiers + // - https://kramdown.gettalong.org/converter/html#auto-ids + // - https://docs.rs/comrak/latest/comrak/options/struct.Extension.html#structfield.header_ids content .trim() .to_lowercase()