Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
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.

Copy link

@LukeLR LukeLR commented Jun 23, 2015

Thanks! Helped me a lot!

@vso-tc

This comment has been minimized.

Copy link

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

Awesome. Thank you!

@JBarna

This comment has been minimized.

Copy link

@JBarna JBarna commented Aug 5, 2015

Thank you.

@hsachdevah

This comment has been minimized.

Copy link

@hsachdevah hsachdevah commented Aug 31, 2015

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.

Copy link

@chop-suey chop-suey commented 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.

@nbarbettini

This comment has been minimized.

Copy link

@nbarbettini nbarbettini commented Sep 17, 2015

Works great. Thanks for the tip 👍

@idkw

This comment has been minimized.

Copy link

@idkw idkw commented Sep 30, 2015

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

@randomcamel

This comment has been minimized.

Copy link

@randomcamel randomcamel commented Oct 8, 2015

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

@TomOnTime

This comment has been minimized.

Copy link

@TomOnTime TomOnTime commented 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
@tomfun

This comment has been minimized.

Copy link

@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';
@willmanio

This comment has been minimized.

Copy link

@willmanio willmanio commented Dec 15, 2015

Thanks mate! 👍

@Aliance

This comment has been minimized.

Copy link

@Aliance Aliance commented Mar 11, 2016

👍

@marsalv

This comment has been minimized.

Copy link

@marsalv marsalv commented Apr 19, 2016

Thanks! 👍

@kakyoism

This comment has been minimized.

Copy link

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

@googlielmo

This comment has been minimized.

Copy link

@googlielmo googlielmo commented Jun 10, 2016

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

Copy link

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

Copy link

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

Copy link

@sandyleo26 sandyleo26 commented 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?

@ljvasey

This comment has been minimized.

Copy link

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

Copy link

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

@pxlshpr

This comment has been minimized.

Copy link

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

Copy link

@janluong janluong commented Mar 17, 2017

How would I get anchors working on github pages?

@Nicofisi

This comment has been minimized.

Copy link

@Nicofisi Nicofisi commented Mar 24, 2017

Thanks!

@refs

This comment has been minimized.

Copy link

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

Copy link

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

Copy link

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

Copy link

@eksperimental eksperimental commented Jun 15, 2017

thank you @eeholmes, such a GREAT ADVICE!

@wayri

This comment has been minimized.

Copy link

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

@Vic-ST

This comment has been minimized.

Copy link

@Vic-ST Vic-ST commented Aug 14, 2017

@wayri Thanks! that works for me.

@kne42

This comment has been minimized.

Copy link

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

Copy link

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

Copy link

@JenkinsY94 JenkinsY94 commented 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)

@wprestong

This comment has been minimized.

Copy link

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

@yegeniy

This comment has been minimized.

Copy link

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

Copy link

@Kristine94 Kristine94 commented Dec 30, 2017

Thanks bro!

@biscaboy

This comment has been minimized.

Copy link

@biscaboy biscaboy commented Feb 2, 2018

Thanks for the tip!

@tibdex

This comment has been minimized.

Copy link

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

Copy link

@alete89 alete89 commented Feb 16, 2018

I send you love!

@g10guang

This comment has been minimized.

Copy link

@g10guang g10guang commented Apr 16, 2018

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

[你好](#你好)

Cannot work.

@Algomorph

This comment has been minimized.

Copy link

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

Copy link

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

Copy link

@caub caub commented May 31, 2018

@srafay

This comment has been minimized.

Copy link

@srafay srafay commented Jul 27, 2018

@shasapo

This comment has been minimized.

Copy link

@shasapo shasapo commented Aug 1, 2018

@splaisan

This comment has been minimized.

Copy link

@splaisan splaisan commented Aug 1, 2018

  1. declare target mark in a regular MD header
    ## My header with a lot of words, and punctuation
    becomes
    ## <a name="some-text">My header with a lot of words, and punctuation</a>

  2. link to the mark with
    [Go to my mark](#some-text)

@sravan953

This comment has been minimized.

Copy link

@sravan953 sravan953 commented Aug 16, 2018

Thanks!

@montaro

This comment has been minimized.

Copy link

@montaro montaro commented Aug 20, 2018

Thanks @asabaylus
Thanks @chop-suey for the tip, this workaround made it work for me
https://gist.github.com/asabaylus/3071099#gistcomment-1574926

@derianpt

This comment has been minimized.

Copy link

@derianpt derianpt commented Sep 24, 2018

Thanks man!

@nisusam

This comment has been minimized.

Copy link

@nisusam nisusam commented Oct 22, 2018

Thanks @asabaylus

@RobertDelwood

This comment has been minimized.

Copy link

@RobertDelwood RobertDelwood commented Nov 7, 2018

None of these work for me. As an example, I use

[Heading Link](#section-i-want)
...
## Section I Want 

And the link goes to a blank page as http://localhost:8080/v2/#section-i-want

Any ideas? I'm using a Mulesoft's API Console, RAML, single page application.

@NirViaje

This comment has been minimized.

Copy link

@NirViaje NirViaje commented Dec 10, 2018

Work or not?

[Work or not?](#work-or-not)

no, am I wrong?

@PythonCoderAS

This comment has been minimized.

Copy link

@PythonCoderAS PythonCoderAS commented Dec 15, 2018

Thank you so much.

Test:

Help

help

@imthenachoman

This comment has been minimized.

Copy link

@imthenachoman imthenachoman commented Feb 12, 2019

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

Thank you for this information @TomOnTime. I was able to use it to create https://imthenachoman.github.io/nGitHubTOC/. It's a simple webpage to create TOC from GitHub markdown..

@ttous

This comment has been minimized.

Copy link

@ttous ttous commented Feb 26, 2019

Thanks @imthenachoman! It helped me realise that this header:
## [0.0.2] - 2019-02-24
should be linked to with this anchor:
[0.0.2](#002---2019-02-24)
which may not be totally intuitive, but @TomOnTime explained it clearly 👍 .

@gfilipiak

This comment has been minimized.

Copy link

@gfilipiak gfilipiak commented Mar 11, 2019

👍

@afelopez

This comment has been minimized.

Copy link

@afelopez afelopez commented Mar 22, 2019

Thanks a lot! it's very useful.

@Nandtrocity

This comment has been minimized.

Copy link

@Nandtrocity Nandtrocity commented May 8, 2019

This is another "thank you" message.

@khastation

This comment has been minimized.

Copy link

@khastation khastation commented Jun 4, 2019

@Velojet

This comment has been minimized.

Copy link

@Velojet Velojet commented Jun 9, 2019

My problem was linking to subheadings with the same name as a subheading in another section.
@splaisan provided me with the solution: a named anchor link, so:
# Section 1 Heading
## Subheading
# Section 2 Heading
## <a name="subheading-2">Subheading</a>

@ThanasisMattas

This comment has been minimized.

Copy link

@ThanasisMattas ThanasisMattas commented Aug 10, 2019

Can the anchor (or a link) at a header be written in a smaller fond?

Tried <span style="font-size:small;">[link_name]</span>, but it didn't work on github.

@capgunmedia

This comment has been minimized.

Copy link

@capgunmedia capgunmedia commented Aug 12, 2019

Does this need to be posted to a live server to work?

@bringbackthedog

This comment has been minimized.

Copy link

@bringbackthedog bringbackthedog commented Sep 28, 2019

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.

Thanks! Just what I was looking for

@ScriptAutomate

This comment has been minimized.

Copy link

@ScriptAutomate ScriptAutomate commented Oct 23, 2019

I referenced this conversation on StackOverflow, since this gist conversation includes interesting comments about anchors all throughout!

@teerasej

This comment has been minimized.

Copy link

@teerasej teerasej commented Jan 25, 2020

One of the most useful gist, Cheer!

@tty7tyil

This comment has been minimized.

Copy link

@tty7tyil tty7tyil commented Feb 2, 2020

* 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, '')
}

For anyone trying to deal with unicode charecters:

I think exclude is better then include every possible punctuation.

This regex [^\w\u4e00-\u9fff\- ] will exclude all word, underscore, hyphen, space, CJK character, and select everything else.

One demonstration of the superiority of this is that it will include emojis while your regex does not.

@sunguard

This comment has been minimized.

Copy link

@sunguard sunguard commented Apr 14, 2020

@ochen1

This comment has been minimized.

Copy link

@ochen1 ochen1 commented Apr 23, 2020

Thank you!

@antonio-petricca

This comment has been minimized.

Copy link

@antonio-petricca antonio-petricca commented May 4, 2020

Thank you

@sunilyadav8

This comment has been minimized.

Copy link

@sunilyadav8 sunilyadav8 commented May 17, 2020

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

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

## [Section I Want] 

Thank you.

@Mardiniii

This comment has been minimized.

Copy link

@Mardiniii Mardiniii commented May 17, 2020

Thank you so much for this gist! 🙌 🙌 🙌 🙌

@holylander

This comment has been minimized.

Copy link

@holylander holylander commented May 20, 2020

thanks a lot for this info :)

@XDracam

This comment has been minimized.

Copy link

@XDracam XDracam commented May 21, 2020

Shows up in Google Search, thanks for spreading the knowledge!

@svakam

This comment has been minimized.

Copy link

@svakam svakam commented Jun 5, 2020

Sweeeeet

@felixtal

This comment has been minimized.

Copy link

@felixtal felixtal commented Jun 17, 2020

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.

Great tip. Thanks!

@ntrel

This comment has been minimized.

Copy link

@ntrel ntrel commented Jun 29, 2020

Does Markdown have any way of just linking to a heading without repeating yourself?

I want to link to [Heading] without having to type [Heading](#heading).

Heading
-------

When Heading is long this is very tiresome.

@JeffreyBenjaminBrown

This comment has been minimized.

Copy link

@JeffreyBenjaminBrown JeffreyBenjaminBrown commented Jun 29, 2020

Linking to a subsection of another file in the same repo is also possible:

[description](../relative/link/to/file.md#section-name-with-dashes-instead-of-spaces)

Capitalization matters.

Some extraneous newlines make the above a little more readable:

[description]
(../relative/link/to/file.md
#
section-name-with-dashes-instead-of-spaces)

I imagine the same trick works if you give an absolute link to a markdown file in a different repo.

@HugoCortell

This comment has been minimized.

Copy link

@HugoCortell HugoCortell commented Jul 4, 2020

How can I make an anchor that does not render?
I have a page that is constantly updated and I wanted to make a link that leads to the button of the page, so I added a textless anchor to the button, but it does not work!

@rupertjeff

This comment has been minimized.

Copy link

@rupertjeff rupertjeff commented Jul 6, 2020

@ntrel Try this alternate method of linking:

I want to link to [Heading] without having to type [Heading].

Heading
--------

... more copy here as needed...

[Heading]: #heading

Wherever it sees [Heading], Markdown will look for a corresponding link definition, and if it finds one, it will associate it, as long as it's an exact match.

@ntrel

This comment has been minimized.

Copy link

@ntrel ntrel commented Jul 7, 2020

@rupertjeff That's useful if I have multiple links to a long anchor in the same document. I meant that if the link title and anchor id are the same except for the automatic lowercase and hyphenation, it would be nice not to have to repeat the anchor, just like on a wiki.

@coffee-data

This comment has been minimized.

Copy link

@coffee-data coffee-data commented Jul 15, 2020

Note if you test this in "Edit file" mode, you may be warned that it will take you off the page. In my case, I got this warning. Once I committed the changes my anchor link was working perfectly.

@Pavivenkatesan

This comment has been minimized.

Copy link

@Pavivenkatesan Pavivenkatesan commented Jul 17, 2020

What if I have two headings with same name and I want the anchor link to take me to the latter one and not the former?

@saulhg

This comment has been minimized.

Copy link

@saulhg saulhg commented Aug 19, 2020

I am using Markdown web part in Sharepoint and the anchors were not working for me... Then, I realised why.
I wrote #Definición (note the Spanish accent in the "o") and was trying to link to it with [Ir a la definición](#definición).
This didn't work, But then, I checked by viewing source in the Chrome browser and noticed that the accented o was omitted. So, writing [Ir a definición](#definicin) worked just fine!
So, characters like á,é,í,ó,ú,Á,É,Í,Ó,Ú,Ñ,ñ are just omitted in anchors.

@chongchonghe

This comment has been minimized.

Copy link

@chongchonghe chongchonghe commented Aug 23, 2020

Thanks! Very helpful.

Is there a way to create a short name for the section title? Something like this:

# [Star Formation Theory][sft]
[Reference to this section](#sft)
@sergeiudris

This comment has been minimized.

Copy link

@sergeiudris sergeiudris commented Sep 5, 2020

@rv404674

This comment has been minimized.

Copy link

@rv404674 rv404674 commented Sep 20, 2020

If one of my heading is this "## What is goRubu? 🚀", then doing this isn't working?

  • What is goRubu?

Any idea how to fix this?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.