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.)

Just tried this, doesn't seem to work. Do you have a fully functioning live example?

@telamonian Here you go: borekb/apollo-typescript-example#1

Direct links to headings:

• borekb/apollo-typescript-example#1 (comment)
• borekb/apollo-typescript-example#1 (comment)

thanks @borekb! Your live examples do seem to be working for me. Hmm, wonder what I was doing wrong before

Thanks for documenting this! :)

to new comers that encounter issues,

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

1. Make sure you add #user-content- to href as @borekb.
2. Make sure id matches the remaining href, in this case some-heading

Otherwise, it won't work

@cjsjyh I tried it and it's working without prefixing the anchor with #user-content-

For the record - something changed in he way GH renders and now it does now work without user-content prefix being added manually, yet the id is still being prefixed

btw @borekb - thanks for this gist

For future reference, the # text doesn't need to be there.

- [A title](#a-title)

## A title <a href="#a-title" id="a-title"/>

Worked for me.

Kudos!

This is the best thing I've ever come across! Thanks, all! 🚀

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