Create a gist now

Instantly share code, notes, and snippets.

Github Markdown Heading Anchors

Anchors in Markdown

To create an anchor to a heading in github flavored markdown. Add - characters between each word in the heading and wrap the value in parens (#some-markdown-heading) so your link should look like so:

[create an anchor](#anchors-in-markdown)

@LukeLR
LukeLR commented Jun 23, 2015

Thanks! Helped me a lot!

@vso-tc
vso-tc commented Jul 10, 2015

Awesome. Thank you!

@JBarna
JBarna commented Aug 5, 2015

Thank you.

@hsachdevah

My headings are not generating anchor tags so can't create hyperlinks to point to it. Any solution?

@chop-suey

Have you written the anchor name in lowercase? (like [create an anchor](#anchors-in-markdown) instead of [create an anchor](#Anchors-in-markdown))
That's what happened to me.. only worked when i changed all to lowercase.

@nbarbettini

Works great. Thanks for the tip 👍

@idkw
idkw commented Sep 30, 2015

It doesn't seem to work, it just displays (#some-markdown-heading)

@randomcamel

Same result here, it's not interpreting that specially.

@TomOnTime

The code that creates the anchors is here:
https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/toc_filter.rb

  1. It downcases the string
  2. remove anything that is not a letter, number, space or hyphen (see the source for how Unicode is handled)
  3. changes any space to a hyphen.
  4. If that is not unique, add "-1", "-2", "-3",... to make it unique
@tomfun
tomfun commented Nov 16, 2015

I was interested of autodocumentation
in my case I use this code (for git lab)

//... val is input
  var anchor = val.trim().toLowerCase().replace(/[^\w\- ]+/g, ' ').replace(/\s+/g, '-').replace(/\-+$/, '');
  if (usedHeaders.indexOf(anchor) !== -1) {
    var i = 1;
    while (usedHeaders.indexOf(anchor + '-' + i) !== -1 && i++<=10);
    anchor = anchor + '-' + i;
  }
  usedHeaders.push(anchor);
  console.log(val, anchor)//result her!
  return '  '.repeat(level) + '* [' + val + '](#' + anchor + ')\n';
@christianewillman

Thanks mate! 👍

@Aliance
Aliance commented Mar 11, 2016

👍

@marsalv
marsalv commented Apr 19, 2016

Thanks! 👍

@kakyoism

This tip does not work with an anchor containing non-ascii characters, e.g., an English+CJK string like this:

[English中文标题](#English中文标题)

won't lead you to:

English中文标题

I tried adding a white space between the English and the first CJK character in the title, then added a dash in-between. This doesn't create the right link either.

@googlielmo

@kakyoism the correct link is [English中文标题](#english中文标题)
(note the lowercase "e" as explained above)

It will link to:

# English中文标题

@svmotha
svmotha commented Jun 12, 2016 edited

How can I use punctuation in my anchors? I tried using the backslash before the punctuation mark in my case a comma. See below example:

[Ready, set, GO!](#ready\,-set\,-go) 

This didn't work though. Am I doing it wrong, or is it not even possible?

@svmotha
svmotha commented Jun 12, 2016

It's okay, I fixed it. I realized that the anchor can work fine without the inclusion of the punctuation. See example below

[Ready, set, GO!](#ready-set-go)

will result in an anchor that works just fine.

@sandyleo26

This is weird. I have the anchor like ## check out / check in files and the link like [link](#check-in-check-out-files) that doesn't work. From the ruby code I think it should handle it but it doesn't. Why?

@ljvasey
ljvasey commented Nov 28, 2016 edited

Here's a tip -- if you're having trouble with your anchor not working due to misspellings or odd characters, simply hover over your heading on Github, then hover or click the link icon that appears to the left. You can then right click to copy the link location, left click it to go to the URL and view it in your address bar, or simply stay hovered over it and view it in the status bar of your browser.

@stevensonmt

@sandyleo26, your example has check out / check in reversed from the anchor to the link. @svmotha's tip fixed my issue of anchors with special characters.

@pxlshpr
pxlshpr commented Feb 17, 2017 edited

@tomfun the correct regex substitutions for the first line would be:

var anchor = val.trim().toLowerCase().replace(/[^\w\- ]+/g, '').replace(/\s/g, '-').replace(/\-+$/, '');

It's important that every space in the title be converted to a - for the anchor to work – but using \s+ instead of \s prevents this.

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