Create a gist now

Instantly share code, notes, and snippets.

Embed
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

This comment has been minimized.

Show comment
Hide comment
@LukeLR

LukeLR Jun 23, 2015

Thanks! Helped me a lot!

LukeLR commented Jun 23, 2015

Thanks! Helped me a lot!

@vso-tc

This comment has been minimized.

Show comment
Hide comment
@vso-tc

vso-tc Jul 10, 2015

Awesome. Thank you!

vso-tc commented Jul 10, 2015

Awesome. Thank you!

@JBarna

This comment has been minimized.

Show comment
Hide comment
@JBarna

JBarna Aug 5, 2015

Thank you.

JBarna commented Aug 5, 2015

Thank you.

@hsachdevah

This comment has been minimized.

Show comment
Hide comment
@hsachdevah

hsachdevah Aug 31, 2015

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

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

@chop-suey

This comment has been minimized.

Show comment
Hide comment
@chop-suey

chop-suey Sep 16, 2015

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.

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

This comment has been minimized.

Show comment
Hide comment
@nbarbettini

nbarbettini Sep 17, 2015

Works great. Thanks for the tip 👍

Works great. Thanks for the tip 👍

@idkw

This comment has been minimized.

Show comment
Hide comment
@idkw

idkw Sep 30, 2015

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

idkw commented Sep 30, 2015

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

@randomcamel

This comment has been minimized.

Show comment
Hide comment
@randomcamel

randomcamel Oct 8, 2015

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

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

@TomOnTime

This comment has been minimized.

Show comment
Hide comment
@TomOnTime

TomOnTime Oct 11, 2015

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

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

This comment has been minimized.

Show comment
Hide comment
@tomfun

tomfun 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';

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

This comment has been minimized.

Show comment
Hide comment
@christianewillman

christianewillman Dec 15, 2015

Thanks mate! 👍

Thanks mate! 👍

@Aliance

This comment has been minimized.

Show comment
Hide comment
@Aliance

Aliance Mar 11, 2016

👍

Aliance commented Mar 11, 2016

👍

@marsalv

This comment has been minimized.

Show comment
Hide comment
@marsalv

marsalv Apr 19, 2016

Thanks! 👍

marsalv commented Apr 19, 2016

Thanks! 👍

@kakyoism

This comment has been minimized.

Show comment
Hide comment
@kakyoism

kakyoism May 22, 2016

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.

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

This comment has been minimized.

Show comment
Hide comment
@googlielmo

googlielmo Jun 10, 2016

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

It will link to:

# English中文标题

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

It will link to:

# English中文标题

@svmotha

This comment has been minimized.

Show comment
Hide comment
@svmotha

svmotha Jun 12, 2016

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 commented Jun 12, 2016

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

This comment has been minimized.

Show comment
Hide comment
@svmotha

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

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 comment has been minimized.

Show comment
Hide comment
@sandyleo26

sandyleo26 Oct 13, 2016

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?

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

This comment has been minimized.

Show comment
Hide comment
@ljvasey

ljvasey Nov 28, 2016

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.

ljvasey commented Nov 28, 2016

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

This comment has been minimized.

Show comment
Hide comment
@stevensonmt

stevensonmt Feb 12, 2017

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

@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

This comment has been minimized.

Show comment
Hide comment
@pxlshpr

pxlshpr Feb 17, 2017

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

pxlshpr commented Feb 17, 2017

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

@janluong

This comment has been minimized.

Show comment
Hide comment
@janluong

janluong Mar 17, 2017

How would I get anchors working on github pages?

How would I get anchors working on github pages?

@Nicofisi

This comment has been minimized.

Show comment
Hide comment
@Nicofisi

Nicofisi Mar 24, 2017

Thanks!

Thanks!

@zyxan

This comment has been minimized.

Show comment
Hide comment
@zyxan

zyxan Mar 27, 2017

is this still working? can't manage to get it work on my PR, it successfully creates the link but inspecting the DOM headers don't appear to have anchors.

zyxan commented Mar 27, 2017

is this still working? can't manage to get it work on my PR, it successfully creates the link but inspecting the DOM headers don't appear to have anchors.

@duhaime

This comment has been minimized.

Show comment
Hide comment
@duhaime

duhaime Apr 19, 2017

@zyxan This technique works, though the gist could be a little more explicit.

To create an anchor tag in github markup, you just need to create a heading element. Example:

#### Installation guide
Here would be some installation instructions

When GitHub transforms this markdown into html, the #### Installation guide line above will be represented as:

<a href='#installation-guide' id='installation-guide' class='anchor' aria-hidden='true'>Installation guide</a>

You can link to this href with a link that looks like this:

[Read our installation guide](#installation-guide)

I hope that helps!

duhaime commented Apr 19, 2017

@zyxan This technique works, though the gist could be a little more explicit.

To create an anchor tag in github markup, you just need to create a heading element. Example:

#### Installation guide
Here would be some installation instructions

When GitHub transforms this markdown into html, the #### Installation guide line above will be represented as:

<a href='#installation-guide' id='installation-guide' class='anchor' aria-hidden='true'>Installation guide</a>

You can link to this href with a link that looks like this:

[Read our installation guide](#installation-guide)

I hope that helps!

@eeholmes

This comment has been minimized.

Show comment
Hide comment
@eeholmes

eeholmes May 4, 2017

Is there a way to specify the anchor name? As soon as I change my section name, all my links will break. I want to specify the anchor like normal for markdown but the html generated from my README.md file is not working as normal for markdown.

So my README.md has

# This is a section name that I might change {#foo}

Normally, this sort of link would work [link](#foo) but it is not working in the html autogenerated by Github from my README.md file.

eeholmes commented May 4, 2017

Is there a way to specify the anchor name? As soon as I change my section name, all my links will break. I want to specify the anchor like normal for markdown but the html generated from my README.md file is not working as normal for markdown.

So my README.md has

# This is a section name that I might change {#foo}

Normally, this sort of link would work [link](#foo) but it is not working in the html autogenerated by Github from my README.md file.

@eksperimental

This comment has been minimized.

Show comment
Hide comment
@eksperimental

eksperimental Jun 15, 2017

thank you @eeholmes, such a GREAT ADVICE!

thank you @eeholmes, such a GREAT ADVICE!

@wayri

This comment has been minimized.

Show comment
Hide comment
@wayri

wayri Jun 18, 2017

Take me where
I guess markdown behaves quite similar to html. I will attach an example below;

[Take me there](#there_you_go)
[Take me where](#here)

I defined two links with anchor names

below is the first anchor

<a name="there_you_go"></a>Take me there

here is the second anchor

<a name="here"></a>Take me where

here is it in practice

Take me there will take you down
Take me where will take you up
/
Take me there
/
blank space for test
/
/
/
/
/
/
blank space end
/
/

So it does work. Hope this helps

wayri commented Jun 18, 2017

Take me where
I guess markdown behaves quite similar to html. I will attach an example below;

[Take me there](#there_you_go)
[Take me where](#here)

I defined two links with anchor names

below is the first anchor

<a name="there_you_go"></a>Take me there

here is the second anchor

<a name="here"></a>Take me where

here is it in practice

Take me there will take you down
Take me where will take you up
/
Take me there
/
blank space for test
/
/
/
/
/
/
blank space end
/
/

So it does work. Hope this helps

@StevenCopeland

This comment has been minimized.

Show comment
Hide comment
@StevenCopeland

StevenCopeland Aug 14, 2017

@wayri Thanks! that works for me.

@wayri Thanks! that works for me.

@kne42

This comment has been minimized.

Show comment
Hide comment
@kne42

kne42 Aug 19, 2017

@janluong One would think that

# [](#my-custom-anchor-name)My Header Name

would result in what we want – but in GitHub Pages, it is unfortunately irrelevant as it would autogenerate the anchor as #my-header-name instead of #my-custom-anchor-name as one would expect.

I found inserting the following in your .md file to work quite nicely:

your markdown here
<h1 id="my-custom-anchor-name">
  My Header Name
</h1>
your markdown here

Best,
Kira

kne42 commented Aug 19, 2017

@janluong One would think that

# [](#my-custom-anchor-name)My Header Name

would result in what we want – but in GitHub Pages, it is unfortunately irrelevant as it would autogenerate the anchor as #my-header-name instead of #my-custom-anchor-name as one would expect.

I found inserting the following in your .md file to work quite nicely:

your markdown here
<h1 id="my-custom-anchor-name">
  My Header Name
</h1>
your markdown here

Best,
Kira

@kesupile

This comment has been minimized.

Show comment
Hide comment
@kesupile

kesupile Sep 23, 2017

Works like a charm. Make sure the fragment link is all in lowercase

# [Heading Link](#section-i-want)

## [Section I Want] 

kesupile commented Sep 23, 2017

Works like a charm. Make sure the fragment link is all in lowercase

# [Heading Link](#section-i-want)

## [Section I Want] 
@JenkinsY94

This comment has been minimized.

Show comment
Hide comment
@JenkinsY94

JenkinsY94 Sep 25, 2017

I wonder how to create anchor to a sub-heading. For example:

Head 1

Head 2

and I want to add anchor to head 2. I tried this but not working:
[create an anchor](#head-2)

I wonder how to create anchor to a sub-heading. For example:

Head 1

Head 2

and I want to add anchor to head 2. I tried this but not working:
[create an anchor](#head-2)

@wprestong

This comment has been minimized.

Show comment
Hide comment
@wprestong

wprestong Sep 28, 2017

I use the "Display #Anchors" extension to Chrome, and also "Markdown Viewer". When I look at a markdown page in Chrome, I can then see how the anchors are spelled. Some have "-" inserted at the beginning, and some don't, and I don't know what the rules are, but if I follow the spelling used by Chrome, the links work, at least with Chrome.

I use the "Display #Anchors" extension to Chrome, and also "Markdown Viewer". When I look at a markdown page in Chrome, I can then see how the anchors are spelled. Some have "-" inserted at the beginning, and some don't, and I don't know what the rules are, but if I follow the spelling used by Chrome, the links work, at least with Chrome.

@yegeniy

This comment has been minimized.

Show comment
Hide comment
@yegeniy

yegeniy Dec 14, 2017

The anchors don't work if you have an anchor link to the current page in GitHub Pages, generated from MarkDown via https://github.com/blog/2289-publishing-with-github-pages-now-as-easy-as-1-2-3

^ anchors links in header no longer work in GH Pages

The only solution I see is putting HTML into your markdown...

Something along the lines of this at the top of your page:

<a id="-"/>

And instead of [hyper](links) such as [^](#) or [^](#-) use something like the following just above your headers:

<a href="#-">`^`</a> - (click to go to first anchor of this comment)

# Header without an anchor link

this would look something like this:

^ - (click to go to first anchor of this comment)

Header without an anchor link

yegeniy commented Dec 14, 2017

The anchors don't work if you have an anchor link to the current page in GitHub Pages, generated from MarkDown via https://github.com/blog/2289-publishing-with-github-pages-now-as-easy-as-1-2-3

^ anchors links in header no longer work in GH Pages

The only solution I see is putting HTML into your markdown...

Something along the lines of this at the top of your page:

<a id="-"/>

And instead of [hyper](links) such as [^](#) or [^](#-) use something like the following just above your headers:

<a href="#-">`^`</a> - (click to go to first anchor of this comment)

# Header without an anchor link

this would look something like this:

^ - (click to go to first anchor of this comment)

Header without an anchor link

@Kristine94

This comment has been minimized.

Show comment
Hide comment
@Kristine94

Kristine94 Dec 30, 2017

Thanks bro!

Thanks bro!

@biscaboy

This comment has been minimized.

Show comment
Hide comment
@biscaboy

biscaboy Feb 2, 2018

Thanks for the tip!

biscaboy commented Feb 2, 2018

Thanks for the tip!

@tibdex

This comment has been minimized.

Show comment
Hide comment
@tibdex

tibdex Feb 8, 2018

If you want stable anchors to have permalinks in your CHANGELOG.md you can do as explained here.

tibdex commented Feb 8, 2018

If you want stable anchors to have permalinks in your CHANGELOG.md you can do as explained here.

@alete89

This comment has been minimized.

Show comment
Hide comment
@alete89

alete89 Feb 16, 2018

I send you love!

alete89 commented Feb 16, 2018

I send you love!

@g10guang

This comment has been minimized.

Show comment
Hide comment
@g10guang

g10guang Apr 16, 2018

What about all characters in header is all chinese. For example 你好。

[你好](#你好)

Cannot work.

What about all characters in header is all chinese. For example 你好。

[你好](#你好)

Cannot work.

@Algomorph

This comment has been minimized.

Show comment
Hide comment
@Algomorph

Algomorph Apr 16, 2018

For titles with periods (".") in them this doesn't work. Frustrating, because I wanted to put the section/subsection numbers into the headers, i.e. "# 2.3.4 Some Stuff"
[EDIT] Oh, the periods just have to be skipped in the anchor. Would have been useful to know...

Algomorph commented Apr 16, 2018

For titles with periods (".") in them this doesn't work. Frustrating, because I wanted to put the section/subsection numbers into the headers, i.e. "# 2.3.4 Some Stuff"
[EDIT] Oh, the periods just have to be skipped in the anchor. Would have been useful to know...

@ChenYingChou

This comment has been minimized.

Show comment
Hide comment
@ChenYingChou

ChenYingChou Apr 20, 2018

  • Convert to lowercase letters
  • Replace each space with '-'
  • Remove punctuations other than "-" and "_"
  • Remove CJK punctuations
function GithubId(val) {
	return val.toLowerCase().replace(/ /g,'-')
		// single chars that are removed
		.replace(/[`~!@#$%^&*()+=<>?,./:;"'|{}\[\]\\–—]/g, '')
		// CJK punctuations that are removed
		.replace(/[ 。?!,、;:“”【】()〔〕[]﹃﹄“”‘’﹁﹂—…-~《》〈〉「」]/g, '')
}

ChenYingChou commented Apr 20, 2018

  • Convert to lowercase letters
  • Replace each space with '-'
  • Remove punctuations other than "-" and "_"
  • Remove CJK punctuations
function GithubId(val) {
	return val.toLowerCase().replace(/ /g,'-')
		// single chars that are removed
		.replace(/[`~!@#$%^&*()+=<>?,./:;"'|{}\[\]\\–—]/g, '')
		// CJK punctuations that are removed
		.replace(/[ 。?!,、;:“”【】()〔〕[]﹃﹄“”‘’﹁﹂—…-~《》〈〉「」]/g, '')
}
@caub

This comment has been minimized.

Show comment
Hide comment
@caub

caub May 31, 2018

caub commented May 31, 2018

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