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.

@holylander
Copy link

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

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

fefong commented Jul 10, 2020

@shilpamk
Copy link

shilpamk commented Aug 2, 2020

Very helpful. Thank you.

@ElectricRCAircraftGuy
Copy link

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

afraz-khan commented Aug 8, 2021

does it work for a ### heading

@Venryx
Copy link

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

IZVRStudio commented Sep 16, 2021

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

1.1 Heading

@Venryx
Copy link

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)

@JAYD3V
Copy link

JAYD3V commented Nov 28, 2021

IDK if there has been a recent change to the parser since September 16th when the last comment was made in this thread, but the Markdown Preview parser seems to be working differently now as I get highlighting when I don't use the comment. Also I can't seem to get the Anchor links to work, is anyone successfully adding links in there CHANGELOGS.md or README.md files in their VSCode extensions?

CHANGELOG-Markdown-and-AnchorLinks

@JAYD3V
Copy link

JAYD3V commented Nov 28, 2021

SUCCESS AT LAST!

So I got it to work for VSCode extensions & CHANGELOGS, however, the HTML Attribute name fails to work in the VSCode Markdown-preview env.

This is the exact code I used, except that the comment was replaced with a bunch of CHANGELOG.md entries.

[end of file](#eof)

<!-- markdown code between the link & anchor-tag -->

<a id="eof"></a>

# eof

If you want to see the actual formatting of the links in a working document, just install the VSCode extension recently released by Microsoft that allows developers to browse the contents of other developers published extensions: Browse Extension's Publish Contents.

You can probably find the links working in other extensions, but I can guarantee you that you will find working versions of the anchor-links located in the theme that I just published: JAYD3V.developers-dojo

@JAYD3V
Copy link

JAYD3V commented Nov 28, 2021

IDK if there has been a recent change to the parser since September 16th when the last comment was made in this thread, but the Markdown Preview parser seems to be working differently now as I get highlighting when I don't use the comment. Also I can't seem to get the Anchor links to work, is anyone successfully adding links in there CHANGELOGS.md or README.md files in their VSCode extensions?

CHANGELOG-Markdown-and-AnchorLinks


Response to my own post

I FIGURED IT OUT:

There is another post I already made about it in this thread than shows a code snippet that works in VS-Code.

@Venryx
Copy link

Venryx commented Nov 28, 2021

I wonder if it matters whether one uses "id" vs "name" for the anchor link.

name has been working fine for me so far, but it's possible that id works in more programs/environments.

@JAYD3V
Copy link

JAYD3V commented Nov 30, 2021

I couldn't get name to work in V.S. Code, however, that was while testing the README.md document using the VS-Code Markdown-preview extension that comes with the open source editor "out-of-the-box". When viewing a public extension — or extensions — from inside in the VS Code editor, using the extensions view, different software is used to parse and render the markdown. In other words, its really hard to tell what will work where, as there are several small markdown parsers out there, and no standardization among them that I know of. Would be nice to see someone make an attempt at standardization though.

@hseritt
Copy link

hseritt commented Jul 28, 2022

This does not seem to work.

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