Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Github README anchor links

To create anchor links that jump down to different sections of a README (as in an interactive table of contents), first create a heading:
#Real Cool Heading

The anchor link for that heading is the lowercase heading name with dashes where there are spaces. You can always get the anchor name by visiting the README on Github.com and clicking on the anchor that appears when you hover to the left of the heading. Copy everything starting at the #:
#real-cool-heading

Wherever you want to link to your Real Cool Heading section, put your desired text in brackets, followed by the anchor link in parentheses:
[Go to Real Cool Heading section](#real-cool-heading)

See! Easy: Go to Real Cool Heading section

#Real Cool Heading
This is a real cool heading with some real cool content.

@c-harding

This comment has been minimized.

Copy link

@c-harding c-harding commented May 12, 2018

GitHub seems not to be displaying the header correctly: try adding a space after the hash

@camiclakis

This comment has been minimized.

Copy link

@camiclakis camiclakis commented May 15, 2019

GitHub seems not to be displaying the header correctly: try adding a space after the hash

link: [Go to Heading section] (#-this-is-a-heading)
heading: # This is a heading
Notice spaces are covered by "-" so you can fix header and use "# Real Cool Heading" instead of "#Real Cool Heading"
Also in link section there is not space between "]" and "(" I placed it just to visualize example

@fefong

This comment has been minimized.

Copy link

@fefong fefong commented Oct 3, 2019

@l0k3ndr

This comment has been minimized.

Copy link

@l0k3ndr l0k3ndr commented Dec 7, 2019

Thank you. Helped me today.

@Dssdiego

This comment has been minimized.

Copy link

@Dssdiego Dssdiego commented Apr 9, 2020

Thanks!

@Kanwar27

This comment has been minimized.

Copy link

@Kanwar27 Kanwar27 commented Apr 23, 2020

Used aforementioned steps with - instead of # and it helped. Thanks.

@holylander

This comment has been minimized.

Copy link

@holylander holylander commented May 20, 2020

Take into account to:

  • Make all lowercase
  • Remove anything that is not a letter, number, space or hyphen, like :, ', etc
  • Change any space to a hyphen.
@Sukhveer97

This comment has been minimized.

Copy link

@Sukhveer97 Sukhveer97 commented Jul 10, 2020

Take into account to:

  • Make all lowercase
  • Remove anything that is not a letter, number, space or hyphen, like :, ', etc
  • Change any space to a hyphen.

Is there any way for me to add '/' between two words?

@fefong

This comment has been minimized.

Copy link

@fefong fefong commented Jul 10, 2020

@shilpamk

This comment has been minimized.

Copy link

@shilpamk shilpamk commented Aug 2, 2020

Very helpful. Thank you.

@ElectricRCAircraftGuy

This comment has been minimized.

Copy link

@ElectricRCAircraftGuy ElectricRCAircraftGuy commented Oct 9, 2020

@sergeiudris

painfully, github's markdown/rst/asciidoc do not allow to give a header a custom anchor id/link

Actually, it does. Here's how:

<a name="custom_anchor_name"></a>
# some header

Now, link to it with:

[click here to jump to my anchor](#custom_anchor_name)

I do that in my readme here: https://github.com/ElectricRCAircraftGuy/AlfaWiFiAdapterSoftware.

Ex: https://github.com/ElectricRCAircraftGuy/AlfaWiFiAdapterSoftware#AWUS036NH

Something else you might find useful:

  1. center and resize images: https://github.com/ElectricRCAircraftGuy/eRCaGuy_hello_world/blob/master/markdown/github_readme_center_and_align_images.md
@afraz-khan

This comment has been minimized.

Copy link

@afraz-khan afraz-khan commented Aug 8, 2021

does it work for a ### heading

@Venryx

This comment has been minimized.

Copy link

@Venryx Venryx commented Aug 11, 2021

does it work for a ### heading

Yes. (I use it for plenty of ### headings in my readme files)

By the way, it's worth noting that vscode's markdown parser gets confused by:

<a name="custom_anchor_name"></a>
# some header

The a-element makes the header lose its "blue highlighting", making it hard to scan through.

To fix this, I add an html comment before the a-element:

<!----><a name="custom_anchor_name"></a>
# some header

Before:

After:

@IZVRStudio

This comment has been minimized.

Copy link

@IZVRStudio IZVRStudio commented Sep 16, 2021

Does it work when there are numbers on the heading?
Example:

1.1 Heading

@Venryx

This comment has been minimized.

Copy link

@Venryx Venryx commented Sep 16, 2021

Does it work when there are numbers on the heading?

It should, yes. Too lazy to confirm, but I'm 90% sure it will work.

However, make sure you're using the correct auto-generated url (you can right click the anchor icon next to it when hovering, when it's in a readme page, to make sure you get the correct link).

If you're using the manual anchor name (as shown in my previous post), then it is unaffected by the header's text/contents. (you could even remove the header, and the anchor would still work)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment