Something changed in how header anchors are named in the output HTML

[darrelmiller]

We recently started noticing that links in the OpenAPI specification markdown document are broken when rendered on GitHub.
OAI/OpenAPI-Specification#3132

We are seeing reports like the following:

---

Apparently GitHub changed the way it treats anchors embedded in headlines, for example

#### <a name="schemaObject"></a>Schema Object

This used to copy the anchor element verbatim to the HTTP output, and links such as Schema Object worked fine.

Now the anchor name is prefixed with user-content-, resulting in

<a name="user-content-schemaObject">

and all links broken.

---

From my investigation, it appears that GitHub use the html-pipeline project, which uses this commonmarker project, which then uses comrak. It seems like it is comrak that is adding the user-content prefix to the header-ids. However, my Ruby/Rust skills are not nearly strong enough to figure out what changed and why links that were previously ok are now broken.

Any suggestions on how we might resolve this issue would be most appreciated. Thanks.

[gjtorikian]

GitHub doesn't use the html-pipeline project; please let me know if there's verbiage there that suggests otherwise. (They used to use it, but that hasn't been the case for some five years now.)

Furthermore, user-content has been around since at least 2015: https://github.com/gjtorikian/html-proofer/blame/85c7aa07cf9d9a0c5fd46c15daeec043856c0ccf/lib/html_proofer/url_validator/external.rb#L122

I'm going to close this issue, not because I don't care, but because this seems to be something GitHub has changed on their end. I can't really control if they use this gem as a base and then add their own modification. Your best bet is probably http://github.com/support.

[kivikakk]

GitHub has ~always prepended user-content- — to stop user content polluting the global document namespace — but for the same length of time it's also used JavaScript to navigate to the corresponding document fragment; try https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions to see what I mean.

The Wayback machine shows the document tree for this document used to look like this back in 2021:

It now looks like this:

The case difference appears significant — it looks like they stopped lowercasing the existing <a name> in the sanitisation process, but the JavaScript that navigates to the corresponding fragment doesn't expect this. If I change that to user-content-datatypes in the inspector and then reattempt navigation to the #dataType fragment, it works.

Your options are likely:

1. https://github.com/support and ask them to change back how they sanitise existing <a name>s;
2. https://github.com/support and ask them to make their JavaScript work with this case; or,
3. change your Markdown output like so:

   -### <a name="dataTypes"></a>Data Types
   +### <a name="datatypes"></a>Data Types

[darrelmiller]

Thank you for the clarification here. I will follow up with GitHub.