Automatically disambiguate anchor names

Author: goerz

src/expand_bibliography.jl

@@ -362,13 +362,7 @@ function expand_bibliography(node::MarkdownAST.Node, meta, page, doc)
     end
     for (key, entry) in entries_to_show
         if fields[:Canonical]
-            try
-                anchor_key = get_anchor_key(key, bib.anchor_keys)
-            catch exception
-                @error "Cannot generate anchor for $(repr(key)) on page $(warn_loc)" exception
-                push!(doc.internal.errors, :bibliography_block)
-                continue  # skip entry
-            end
+            anchor_key = get_anchor_key(key, bib.anchor_keys)
             # Add anchor that citations can link to from anywhere in the docs.
             if Documenter.anchor_exists(anchors, anchor_key)
                 # Skip entries that already have a canonical bib entry
@@ -422,12 +416,20 @@ end
 # compatibility with CSS selectors, see https://stackoverflow.com/a/79022.
 # Even more importantly, these characters are not supported by the
 # `Documenter.DOM` framework that we use to generate HTML: it will silently
-# drop anything after a colon or period.
-function get_anchor_key(citation_key::String, cache::Bijections.Bijection{String,String})
+# drop anything after a colon or period. The numerical `suffix_index` gets
+# appended to the anchor name if > 0 and can be used to disambiguate labels.
+function get_anchor_key(
+    citation_key::String,
+    cache::Bijections.Bijection{String,String};
+    suffix_index::Int64=1
+)
     if haskey(cache, citation_key)
         anchor_key = cache[citation_key]
     else
         anchor_key = normalize_anchor(citation_key) # => [A-Za-z0-0_-]
+        if suffix_index > 1
+            anchor_key *= "-$suffix_index"
+        end
         if !startswith(anchor_key, r"[A-Za-z]")
             # Anchors must start with a letter. Instead of rejecting "invalid"
             # anchors, we just prepend something arbitrary.
@@ -438,8 +440,14 @@ function get_anchor_key(citation_key::String, cache::Bijections.Bijection{String
             # duplicates here.
             cache[citation_key] = anchor_key
         catch
-            msg = "Cannot generate HTML anchor for citation key $(repr(citation_key)): normalizes to ambiguous $(repr(anchor_key)) conflicting with citation key $(repr(cache(anchor_key)))"
-            error(msg)
+            suffix_index += 1
+            msg = "HTML anchor for citation key $(repr(citation_key)) normalizes to ambiguous $(repr(anchor_key)) conflicting with citation key $(repr(cache(anchor_key))). Disambiguating with suffix \"-$(suffix_index)\""
+            @warn(msg)
+            if suffix_index < 100
+                return get_anchor_key(citation_key, cache; suffix_index)
+            else
+                error("Internal error: cannot find disambiguated anchor key")
+            end
         end
         @debug "Generated anchor key $(repr(anchor_key)) for citation key $(repr(citation_key))"
     end

test/test_anchor_keys.jl

@@ -25,10 +25,9 @@ include("run_makedocs.jl")
     c = IOCapture.capture(rethrow=Union{}) do
         get_anchor_key("AbsilMahonySepulchre.2008", cache)
     end
-    @test c.value isa ErrorException
-    msg = "Cannot generate HTML anchor for citation key \"AbsilMahonySepulchre.2008\": normalizes to ambiguous \"AbsilMahonySepulchre2008\" conflicting with citation key \"AbsilMahonySepulchre:2008\""
-    @Test c.value.msg == msg
-
+    @test c.value == "AbsilMahonySepulchre2008-2"
+    msg = "Warning: HTML anchor for citation key \"AbsilMahonySepulchre.2008\" normalizes to ambiguous \"AbsilMahonySepulchre2008\" conflicting with citation key \"AbsilMahonySepulchre:2008\". Disambiguating with suffix \"-2\""
+    @test contains(c.output, msg)
 
 end
 
@@ -54,16 +53,18 @@ end
         @test success
 
         @test bib.anchor_keys["Chirikjian:2012"] == "Chirikjian2012"
+        @test bib.anchor_keys["Chirikjian2012"] == "Chirikjian2012-2"
 
-        @test contains(output, "Error: Cannot generate anchor for \"Chirikjian2012\"")
         @test contains(output, "normalizes to ambiguous \"Chirikjian2012\"")
 
         #! format: off
         index_html = read(joinpath(dir, "build", "index.html"), String)
         @Test contains(index_html, "<a href=\"references/#Chirikjian2012\">")
+        @Test contains(index_html, "<a href=\"references/#Chirikjian2012-2\">")
 
         references_html = read(joinpath(dir, "build", "references", "index.html"), String)
         @Test contains(references_html, "<div id=\"Chirikjian2012\">")
+        @Test contains(references_html, "<div id=\"Chirikjian2012-2\">")
         #! format: on
 
     end

test/test_anchor_keys/src/index.md

@@ -2,4 +2,4 @@
 
 You can read more about the theory of Lie groups for example in [Chirikjian:2012](@cite).
 
-Note the ambiguous citations keys, as for Ref. [Chirikjian2012](@cite) leads to errors.
+Note the ambiguous citations keys, as for Ref. [Chirikjian2012](@cite) are automatically disambiguated.