How to link to headings in GitHub issues and pull requests

README.md

How to link to headings in GitHub issues and pull requests

If you have an issue comment / PR description on GitHub, it doesn't automatically get anchors / IDs that you could link to:

What I like to do is to add a visible # character like this:

It renders like this:

Copy/paste-friendly Markdown snippet:

# Some heading <a href="#user-content-some-heading" id="some-heading">#</a>

Don't forget to add the user-content- prefix to href – that's how GitHub transforms custom IDs.

---

Alternatively, if you don't want the visible # character, you could also do this:

It renders like this:

The same URL as before can be used to link to this heading, e.g.:

https://github.com/borekb/example/issues/123#user-content-second-section

(You can use browser dev tools' Inspect element to find out the anchor.)

Thank you!

Why is that needed at all? For many markdown to html converters this works out of the box (just use # Foo and then ...#foo works fine).

In this StackOverflow answer is stated that the best (or most browser-compatible) approach is using name instead of id:

• Take me to [Header1](#pookiie)
• ### <a name="pookie"></a>Header1

Reasoning (from this answer):

Use a name. Using an id isn't necessary in HTML 5 and will create global variables in your JavaScript

See the HTML 5 specification, 5.9.8 Navigating to a fragment identifier - both id and name are used.

It's important to know that most browsers still turn IDs into global variables. Here's a quick test. Using a name avoids creating globals and any conflicts that may result.

Example using a name:

Take me to [pookie](#pookie)

And the destination anchor:

### <a name="pookie"></a>Some heading

In this StackOverflow answer is stated that the best (or most browser-compatible) approach is using name instead of id:

• Take me to [Header1](#pookiie)
• ### <a name="pookie"></a>Header1

Reasoning (from this answer):

Use a name. Using an id isn't necessary in HTML 5 and will create global variables in your JavaScript
See the HTML 5 specification, 5.9.8 Navigating to a fragment identifier - both id and name are used.
It's important to know that most browsers still turn IDs into global variables. Here's a quick test. Using a name avoids creating globals and any conflicts that may result.
Example using a name:

Take me to [pookie](#pookie)

And the destination anchor:

### <a name="pookie"></a>Some heading

@pjmartorell : That's interesting, however I'm unsure that is really a concern within GitHub issue versus building your own website. $0.02