Set Selectors.strict(::Type{XRefResolvers.Header}) = true (#2787)

Author: lgoettgens

CHANGELOG.md

@@ -10,6 +10,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Page category is removed from the search index and now everything is in section category. ([#2762], [#2413])
 * Changed the docstring block accordions from a custom implementation to HTML details+summary tag. ([#2772], [#2773])
 
+### Fixed
+
+* Changed the header crossref step to eagerly fail when encountering a non-unique header slug. ([#2668], [#2787])
+
+  This is **potentially breaking** and may cause some documentation builds to fail.
+  Those previously passed but generated incorrect cross-references.
+  You can fix this by ensuring that you have distinct headers across your markdown pages, or by using the `@id` syntax to give the headers unique slugs.
+
 ## Version [v1.15.0] - 2025-10-22
 
 ### Changed
@@ -2130,6 +2138,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2658]: https://github.com/JuliaDocs/Documenter.jl/issues/2658
 [#2659]: https://github.com/JuliaDocs/Documenter.jl/issues/2659
 [#2662]: https://github.com/JuliaDocs/Documenter.jl/issues/2662
+[#2668]: https://github.com/JuliaDocs/Documenter.jl/issues/2668
 [#2674]: https://github.com/JuliaDocs/Documenter.jl/issues/2674
 [#2675]: https://github.com/JuliaDocs/Documenter.jl/issues/2675
 [#2676]: https://github.com/JuliaDocs/Documenter.jl/issues/2676
@@ -2158,6 +2167,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2772]: https://github.com/JuliaDocs/Documenter.jl/issues/2772
 [#2773]: https://github.com/JuliaDocs/Documenter.jl/issues/2773
 [#2774]: https://github.com/JuliaDocs/Documenter.jl/issues/2774
+[#2787]: https://github.com/JuliaDocs/Documenter.jl/issues/2787
 [JuliaLang/julia#36953]: https://github.com/JuliaLang/julia/issues/36953
 [JuliaLang/julia#38054]: https://github.com/JuliaLang/julia/issues/38054
 [JuliaLang/julia#39841]: https://github.com/JuliaLang/julia/issues/39841

src/cross_references.jl

@@ -161,6 +161,10 @@ module XRefResolvers
     after the last step, [`Documenter.xref`](@ref) issues an error that includes any
     accumulated error messages from the steps. Failure to resolve an `@ref` link will fail
     [`Documenter.makedocs`](@ref) if it is not called with `warnonly=true`.
+    A step may choose to make the entire pipeline fail when it encounters a case that obviously
+    has to be resolved by this step, but cannot be resolved due to an error (for example,
+    a non-unique header slug). In that case, the step should set its [`Selectors.strict`](@ref)
+    to `true`.
 
     The default pipeline could be extended by plugins using the general [`Selectors`](@ref)
     machinery.
@@ -237,6 +241,8 @@ function Selectors.runner(::Type{XRefResolvers.Header}, node, slug, meta, page,
     return namedxref(node, slug, meta, page, doc, errors)
 end
 
+Selectors.strict(::Type{XRefResolvers.Header}) = true
+
 
 function Selectors.matcher(::Type{XRefResolvers.Issue}, node, slug, meta, page, doc, errors)
     return (xref_unresolved(node) && occursin(r"#[0-9]+", slug))