Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
darrelmiller opened this issue Feb 5, 2023 · 3 comments
Closed

Comments

@darrelmiller
Copy link

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
Copy link
Owner

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
Copy link
Collaborator

kivikakk commented Feb 5, 2023

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:

image

It now looks like this:

image

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
Copy link
Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants