696

Is there markdown syntax for the equivalent of:

Take me to <a href="#pookie">pookie</a>

... 

<a name="pookie">this is pookie</a>

15 Answers 15

927
Take me to [pookie](#pookie)

should be the correct markdown syntax to jump to the anchor point named pookie.

To insert an anchor point of that name use HTML:

<a name="pookie"></a>

Markdown doesn't seem to mind where you put the anchor point. A useful place to put it is in a header. For example:

### <a name="tith"></a>This is the Heading

works very well. (I'd demonstrate here but SO's renderer strips out the anchor.)

Note on self-closing tags and id= versus name=

An earlier version of this post suggested using <a id='tith' />, using the self-closing syntax for XHTML, and using the id attribute instead of name.

XHTML allows for any tag to be 'empty' and 'self-closed'. That is, <tag /> is short-hand for <tag></tag>, a matched pair of tags with an empty body. Most browsers will accept XHTML, but some do not. To avoid cross-browser problems, close the tag explicitly using <tag></tag>, as recommended above.

Finally, the attribute name= was deprecated in XHTML, so I originally used id=, which everyone recognises. However, HTML5 now creates a global variable in JavaScript when using id=, and this may not necessarily be what you want. So, using name= is now likely to be more friendly.

(Thanks to Slipp Douglas for explaining XHTML to me, and nailer for pointing out the HTML5 side-effect — see the comments and nailer's answer for more detail. name= appears to work everywhere, though it is deprecated in XHTML.)

30
  • 3
    You can't see how to link to your heading demo after StackOverflow renders the HTML because their rendered is stripping out your <a> tag. That is, you can't in StackOverflow Markdown. Apr 13, 2012 at 18:58
  • 4
    However, this will work in other, more-liberal Markdown renderers, but you'll need a closing <a> tag; the <a> tag doesn't allow self-closing. Also, I found my browser to skip past the header unless the <a> tag is before the header's contents. Corrections made to your examples. Apr 13, 2012 at 19:22
  • 1
    Slipp: Thanks for the explanation. Self-closing <a> tags work fine for me. Can you give a reference? Apr 17, 2012 at 9:54
  • 4
    @Slipp: OK I think I understand, now. You coded <a id="hi"/> rest of doc, but it was treated like <a id="hi"> rest of doc</a>. (And the element analysis of the page shows this, too.) My mistake: I looked at the elements displayed not the raw source. Do you think the answer should be modified, in light of this observation? May 16, 2012 at 13:56
  • 7
    The name attribute also creates global variables (see stackoverflow.com/questions/3434278/…), so you might as well use the id attribute as the target of fragment identifier URLs, as intended.
    – Bobby Jack
    Jun 15, 2015 at 9:22
144

On bitbucket.org the voted solution wouldn't work. Instead, when using headers (with ##), it is possible to reference them as anchors by prefixing them as #markdown-header-my-header-name, where #markdown-header- is an implicit prefix generated by the renderer, and the rest is the lower-cased header title with dashes replacing spaces.

Example

## My paragraph title

will produce an implicit anchor like this

#markdown-header-my-paragraph-title

The whole URL before each anchor reference is optional, i.e.

[Some text](#markdown-header-my-paragraph-title)

is equivalent of

[Some text](https://bitbucket.org/some_project/some_page#markdown-header-my-paragraph-title) 

provided that they are in the same page.

Source: https://bitbucket.org/tutorials/markdowndemo/overview (edit source of this .md file and look at how anchors are made).

8
  • 1
    This may do as well. According to this: confluence.atlassian.com/bitbucket/…, bitbucket supports the Table of Contents extension which can auto-generate links and anchors based on the document headers. The TOC extension is documented here: pythonhosted.org/Markdown/extensions/toc.html Add the text "[TOC]" to the beginning of the document for it to be generated. Jun 29, 2016 at 19:47
  • 13
    In Github, ## My paragraph title will produce the following anchor user-content-my-paragraph-title, so you can reference it with [Some text](#user-content-my-paragraph-title). However, I haven't found official documentation for this.
    – toto_tico
    Jul 11, 2016 at 23:02
  • This helped me on Bitbucket as well - works like a charm. Jul 28, 2016 at 21:41
  • 2
    This is useful information; thank you. However, markdown renderers without the extensions won't generate these anchors for you, and clashing heading names will result in clashing anchor ids (or some unhelpful distinguishing trick, like number suffices). Explicit anchor ids are better, more controllable, not subject to random changes due to text updates (see trick above) and useful for anchoring more than just headers. Both techniques are needed in general. Sep 18, 2016 at 14:55
  • 1
    The accepted answer works for bitbucket now and this doesn't.
    – heez
    Nov 19, 2018 at 21:35
76

Use a name. Using an id isn't necessary in HTML 5 and will create global variables in your JavaScript

See the HTML 5 specification, 5.9.8 Navigating to a fragment identifier - both id and name are used.

It's important to know that most browsers still turn IDs into global variables. Here's a quick test. Using a name avoids creating globals and any conflicts that may result.

Example using a name:

Take me to [pookie](#pookie)

And the destination anchor:

### <a name="pookie"></a>Some heading
17
  • 6
    Downvoting. The global variable argument is weak since you shouldn't be (directly) defining global variables in your JS anyway, so no conflict will happen. Also, the semantics of name and id are different. Sep 11, 2014 at 18:22
  • 12
    @MarnenLaibow-Koser Nobody is discussing defining global variables in JS. Making an ID in HTML creates a global window.someid in most browsers. Sep 12, 2014 at 9:42
  • 19
    @MarnenLaibow-Koser Many libraries (i.e., not your own JS, but someone else's) use a single global - for example, fineuploader. If you make an element with an ID of fineuploader, you will be unable to use the fineuploader module. Avoiding creating unnecessary globals helps avoid those conflicts. Sep 14, 2014 at 13:34
  • 6
    I would be interested to run some tests of that case and find out which one takes precedence. I appreciate the theoretical issue, but in years of client-side development, I've never had an ID break any client-side JS (provided the HTML was otherwise valid). I'll continue to use them when they're semantically appropriate until I run into actual problems. Mar 2, 2015 at 2:16
  • 3
    "'drop this <script> in' generally doesn't pollute the global namespace" Testing popular libraries shows they do - see window.Stripe window.olark, and window.twttr. Read more at 2ality.com/2012/08/ids-are-global.html Jan 20, 2016 at 13:32
28

Markdown Anchor supports the hashmark, so a link to an anchor in the page would simply be [Pookie](#pookie)

Generating the anchor is not actually supported in Gruber Markdown, but is in other implementations, such as Markdown Extra.

In Markdown Extra, the anchor ID is appended to a header or subhead with {#pookie}.

Github Flavored Markdown in Git repository pages (but not in Gists) automatically generates anchors with several markup tags on all headers (h1, h2, h3, etc.), including:

  • id="user-content-HEADERTEXT"
  • class="anchor"
  • href="#HEADERTEXT"
  • aria-hidden="true" (this is for an svg link icon that displays on mouseover)

Excluding the aria/svg icon, when one writes:

  • # Header Title

Github generates:

  • <h1><a id="user-content-header-title" class="anchor" href="#header-title">Header Title</a></h1>

Therefore, one need do nothing to create the header links, and can always link to them with:

  • Link to the [Header Title](#header-title)
2
  • 2
    This is the one that works for me. [Header Title](#header-title) May 7, 2021 at 16:48
  • This works on Azure Devops too. Also the ### Header Title header can have uppercase characters, but the (#header-title) markdown is all lowercase. And had a comma which was encoded as %2C which I used in markdown like this (#header-title%2C-etc) Jul 21 at 23:45
25

For anyone who is looking for a solution to this problem in GitBook. This is how I made it work (in GitBook). You need to tag your header explicitly, like this:

# My Anchored Heading {#my-anchor}

Then link to this anchor like this

[link to my anchored heading](#my-anchor)

Solution, and additional examples, may be found here: https://seadude.gitbooks.io/learn-gitbook/

1
  • Works like a charm, but as i just found out the anchor should be lower case only, otherwise it won't work
    – j_elfering
    Jan 17, 2022 at 14:32
17

There's no readily available syntax to do this in the original Markdown syntax, but Markdown Extra provides a means to at least assign IDs to headers — which you can then link to easily. Note also that you can use regular HTML in both Markdown and Markdown Extra, and that the name attribute has been superseded by the id attribute in more recent versions of HTML.

0
12

Late to the party, but I think this addition might be useful for people working with rmarkdown. In rmarkdown there is built-in support for references to headers in your document.

Any header defined by

# Header

can be referenced by

get me back to that [header](#header)

The following is a minimal standalone .rmd file that shows this behavior. It can be knitted to .pdf and .html.

---
title: "references in rmarkdown"
output:
  html_document: default
  pdf_document: default
---

# Header

Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. 

Go back to that [header](#header).
9

As we see (from the answers), there is no standard way for this; and different markdown processors would differ in their markdown extensions that offer this kind of possibilities.

With pandoc, you can get what you asked for like this:

Take me to [pookie](#pookie)

...

[this is pookie]{#pookie}

This gives (with pandoc-2.9.2.1):

<p>Take me to <a href="#pookie">pookie</a></p>
<p>…</p>
<p><span id="pookie">this is pookie</span></p>

One can also make an empty span with an anchor id:

Take me to [pookie](#pookie)

...

this is pookie []{#pookie}

which would produce:

<p>Take me to <a href="#pookie">pookie</a></p>
<p>…</p>
<p>this is pookie <span id="pookie"></span></p>

Apart from this, for pandoc and for most common markdown generators, you have a simple self generated anchor in each header. (See that and other answers here for convenient ways to (auto)generate and refernce such anchors.)

7

Using the latest Markdown, you should be able to use the following syntax:

[](){:name='anchorName'}

This should create the following HTML:

<a name="anchorName"></a>

If you wanted the anchor to have text, simply add the anchor text within the square brackets:

[Some Text](){:name='anchorName'}

4
  • 4
    It seems like only Maruku knows about this syntax. See the babelmark.
    – Ulysse BN
    May 15, 2019 at 13:03
  • 1
    Does not work in VS Code Apr 14, 2022 at 15:39
  • 3
    There is no such thing as "the latest markdown". There are various implementations/dialects of it.
    – oligofren
    Apr 28, 2022 at 7:45
  • Inspired by this and michelf.ca/projects/php-markdown/extra/#spe-attr, I have this working in VSCode by adding {#anchor_name} at the EOL where I want to create it, then reference it with [link name](#anchor_name). Note that I have, among others, the Markdown extended extension installed.
    – silopolis
    2 days ago
7

For most common markdown generators. You have a simple self generated anchor in each header. For instance with pandoc, the generated anchor will be a kebab case slug of your header.

 echo "# Hello, world\!" | pandoc
 # => <h1 id="hello-world">Hello, world!</h1>

Depending on which markdown parser you use, the anchor can change (take the exemple of symbolrush and La muerte Peluda answers, they are different!). See this babelmark where you can see generated anchors depending on your markdown implementation.

2
  • @imz -- Ivan Zakharyaschev, I've rolled back your edit. It was a really different writing and hard for me to understand the point. The goal of this answer is mostly to link to babelmark and hint that there are plenty solution and answer should not focus on a specific implementation... Maybe commeting your point is a good idea though :)
    – Ulysse BN
    Nov 10, 2020 at 16:39
  • 1
    Yes, that's OK. Maybe I'll write it down separately. Nov 10, 2020 at 20:43
3

For anyone who likes to use headers with different levels, it's useful to note that the link to the header should only ever use a single #, regardless of the header's level:

# This is an H1
## This is an H2
### This is an H3
...
[Take me to H3](#this-is-an-H3)
[Take me to H1](#this-is-an-H1)
[This won't work](##-this-is-an-H2)

2

I will quickly complement for cases where the header contains emojis, in that case it is simpler to just remove the emoji in the link of the reference. For example

# ⭐ Title 2
....
[Take me to title 2](#-title-2)

There are some cases where this does not work for a weird reason, for example here in setup. The solution in that case is to include the whole code for the emoji as well.

1

This example of a table of contents final view

https://i.stack.imgur.com/zUcXt.png

This code to how to produce the table of contents above

https://i.stack.imgur.com/yCxId.png

cell

## Table of Contents
<ul>
<li><a href="#intro">Introduction</a></li>
<li><a href="#wrangling">Data Wrangling</a></li>
<li><a href="#eda">Exploratory Data Analysis</a></li>
<li><a href="#conclusions">Conclusions</a></li>
</ul>

cell

<a id='intro'></a>
### Introduction

cell

<a id='wrangling'></a>
### Data Wrangling

cell

<a id='eda'></a>
### Exploratory Data Analysis

cell

<a id='conclusions'></a>
### Conclusions
1

Special case not covered in the other answers:

If your heading has parentheses, just ignore them from your hyphen-separated key.

Example:

## My paragraph title (MpT)


[Some text](#my-paragraph-title-mpt)

At least, this works in Visual Studio Code rendered.

0

About special characters

Not sure it applies to all MarkDown processors, but special characters (including accented letters) as well as suites of special characters may be replaced by a single hyphen :

# L’insoutenable légèreté de l’Être

will give

#l-insoutenable-l-g-ret-de-l-tre

Suffixing

Some processors will add a suffix to prevent conflicts :

# Foobar
## Foobar
### Baz
### Foobar
# Foobar

will give

#foobar-1
#foobar-2
#baz-1
#foobar-3
#foobar-4

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.