Broken anchor links within markdown documents

[uecasm]

Example: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-introduction

Anchor links to this document are commonplace elsewhere on the Internet, and are used extensively within the document itself. However it appears that somewhere in the github rendering pipeline an additional prefix is being inserted which breaks things.

An example link to the introduction section from within the markdown source:

* [In: Introduction](#S-introduction)

The introduction section anchor target in the markdown source:

# <a name="S-introduction"></a>In: Introduction

The rendered link:

<a href="#S-introduction">In: Introduction</a>

The rendered target (with some pretty-printing):

<h1 dir="auto">
  <a id="user-content-in-introduction" class="anchor" aria-hidden="true" href="#in-introduction"><svg ... /></a>
  <a name="user-content-S-introduction"></a>In: Introduction
</h1>

There are two problems with this:

• The auto-generated section anchor specifies an id of user-content-in-introduction, but then an href of #in-introduction. Prefix or not doesn't especially matter (unless someone has already externally copied such a link) but these do need to be the same.
• The <a name/> anchor explicitly specified in the markdown source has also erroneously had a user-content- prefix added to it, which is absolutely a bug.

So the quick fix might be to find and boot whatever is adding those prefixes, though that may not be the best fix depending on the history.

[bitofbreeze]

+1 this is obviously a bug. If someone would like an example of the issue, check out my app where I use this package's output to render a repo's readme https://www.starter.place/jihchi/vitejs-template-react-rescript#vite-react-rescript-starter

[Marcono1234]

The user-content- prefix is most likely used for security reasons; this is also done by multiple other sites. If I recall correctly I read in the past that this is done to avoid collisions of id and name attributes with existing attributes on the page needed to make the page work. E.g. imaging some JavaScript code on the page tries to get an HTML element with a specific id and suddenly it selects the user provided one.

When using the custom anchor with a URL fragment (e.g. ...#in-introduction) it appears GitHub automatically adds the user-content- prefix again. However, that behavior apparently changed in the past and if the anchor contains uppercase characters (in your case the S), this does not work anymore.

You could of course add the user-content- prefix manually to the fragment, e.g. #user-content-S-introduction, but it looks like the browser then scrolls exactly to that HTML element and does not account for the floating headers at the top. So the content which should be visible is actually hidden by the floating headers.

I have created https://github.com/orgs/community/discussions/50962 asking if there is official support for custom HTML anchors, or if this just happens to work. Though maybe there is a better place for that question.

[github-actions[bot]]

Stale issue message

[uecasm]

Bug still present message