Escape special characters in keys when using as anchor

[kellertuer]

Hi,
we are using DocumenterCitations a lot and it is super great.

I had a problem with the links to the literature that I could never narrow down. Today I noticed what the problem is: When having special characters in the key of an entry, in our case espeially a :, the direct links to the references get rendered as

https://juliamanifolds.github.io/Manifolds.jl/stable/misc/references/#Chirikjian:2012

Which does not work, since :is not a valid part of a URL.

For reference the BibTeX entry is
https://github.com/JuliaManifolds/Manifolds.jl/blob/0c2a7b7a435c552379b3393dccce3de6fa514bfe/docs/src/references.bib#L270-L279

Currently it also seems maybe the anchor (id) gets even shortened?

Would it maybe be possible both for URLs and anchors to use URL escape codes https://docs.microfocus.com/OMi/10.62/Content/OMi/ExtGuide/ExtApps/URL_encoding.htm so that the URL above would read

https://juliamanifolds.github.io/Manifolds.jl/stable/misc/references/#Chirikjian%3A2012

and the id as well (this link currently does not work because the id for this example is cut off at the :)?
It is hopefully (just) using https://juliaweb.github.io/HTTP.jl/stable/reference/#URIs.escapeuri
That would be great!

Otherwise maybe document that those characters should not be in keys – though then we would have to rework all our keys (but well...).

[goerz]

I don’t see any reason to prohibit colons in citation keys, so yes, I consider this a bug. I’ll have a look when I have a chance

[goerz]

It turns out that the HTML4 standard requires that anchor names must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods ("."). Dots and colons are further problematic for 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, cf.

Currently it also seems maybe the anchor (id) gets even shortened?

That's what's actually causing the issue here. Without that "bug", colons would technically work (with most browsers). Still, I think the correct solution here is to generate anchor names from citation keys via a normalization that restricts the anchor IDs to ASCII alphanumerics with underscores and hyphens.