Github Markdown Heading Anchors

gistfile1.md

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)

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

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.

thank you @eeholmes, such a GREAT ADVICE!

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 Thanks! that works for me.

@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

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

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

## [Section I Want] 

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

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

Thanks bro!

Thanks for the tip!

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

I send you love!

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

[你好](#你好)

Cannot work.

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

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

Scroll up ^ :)

testing the anchors

create an anchor

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)

Thanks!

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

Thanks man!

Thanks @asabaylus

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.

Work or not?

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

no, am I wrong?

Thank you so much.

Test:

Help

help

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

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