[markdown] How to link to part of the same document in Markdown?

I am writing a large Markdown document and would like to place a table of contents of sorts at the beginning that will provide links to various locations in the document. How can I do this?

I tried using:

[a link](# MyTitle)

where MyTitle is a title within the document but this didn't work.

In addition to the above answers,

When setting the option number_sections: true in the YAML header:

number_sections: TRUE

RMarkdown will autonumber your sections.

To reference those autonumbered sections simply put the following in your R Markdown file:

[My Section]

Where My Section is the name of the section

This seems to work regardless of the section level:

# My section

## My section

### My section

Universal solutions

This question seems to have a different answer according to the markdown implementation.
In fact, the official Markdown documentation is silent on this topic.
In such cases, and if you want a portable solution, you could use HTML.

Before any header, or in the same header line, define an ID using some HTML tag.
For example: <a id="Chapter1"></a>
You will see this in your code but not in the rendered document.

Full example:

See a full example (online and editable) here.

## Content

* [Chapter 1](#Chapter1)
* [Chapter 2](#Chapter2)

<div id="Chapter1"></div>
## Chapter 1

Some text here.  
Some text here.
Some text here.

## Chapter 2 <span id="Chapter2"><span>

Some text here.  
Some text here.
Some text here.

To test this example, you must add some extra space between the content list and the first chapter or reduce the window height.
Also, do not use spaces in the name of the ids.

Gitlab uses GitLab Flavored Markdown (GFM)

Here "all Markdown-rendered headers automatically get IDs"

One can use mouse to :

• move mouse over header
• move mouse over hover selector which becoms visible to the left from header

• copy and save link using right mouse click

  For example in README.md file I have header:

## series expansion formula of the Boettcher function

which gives a link :

https://gitlab.com/adammajewski/parameter_external_angle/blob/master/README.md#series-expansion-formula-of-the-boettcher-function

Prefix can be removed so the link here is simply

file#header

which here means:

README.md#series-expansion-formula-of-the-boettcher-function

Now it can be used as :

[series expansion formula of the Boettcher function](README.md#series-expansion-formula-of-the-boettcher-function)

One can also do it manually: replace spaces with hyphen sign.

Live example is here

yes, markdown does do this but you need to specify the name anchor <a name='xyx'>.

a full example,

this creates the link
[tasks](#tasks)

later in the document, you create the named anchor (whatever it is called).

<a name="tasks">
   my tasks
</a>

note that you could also wrap it around the header too.

<a name="tasks">
### Agile tasks (created by developer)
</a>

This may be out-of-date thread but to create inner document links in markdown in Github use...
(NOTE: lowercase #title)

# Contents
 - [Specification](#specification) 
 - [Dependencies Title](#dependencies-title) 

## Specification
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. 

## Dependencies Title
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. 

A good question was made so I have edited my answer;

An inner link can be made to any title size using - #, ##, ###, #### I created a quick example below... https://github.com/aogilvie/markdownLinkTest

Using kramdown, it seems like this works well:

[I want this to link to foo](#foo)
....
....
{: id="foo"}
### Foo are you?

I see it's been mentioned that

[foo][#foo]
....
#Foo

works efficiently, but the former might be a good alternative for elements besides headers or else headers with multiple words.

Some more spins on the <a name=""> trick:

<a id="a-link"></a> Title
------

#### <a id="a-link"></a> Title (when you wanna control the h{N} with #'s)

Some additional things to keep in mind if ya ever get fancy with symbols within headings that ya want to navigate to...

# What this is about


------


#### Table of Contents


- [About](#what-this-is-about)

- [⚡ Sunopsis](#9889-tldr)

- [:gear: Grinders](#it-grinds-my-gears)

- [Attribution]


------


## ⚡ TLDR


Words for those short on time or attention.


___


## It Grinds my :gear:s


Here _`:gear:`_ is not something like ⚙ or ⛭


___


## ⛤ Attribution


Probably to much time at a keyboard



[Attribution]: #9956-attribution

... things like #, ;, &, and : within heading strings are generally are ignored/striped instead of escaped, and one can also use citation style links to make quick use easier.

Notes

GitHub supports the :word: syntax in commits, readme files, etc. see gist(from rxaviers) if using'em is of interest there.

And for just about everywhere else decimal or hexadecimal can be used for modern browsers; the cheat-sheet from w3schools is purdy handy, especially if using CSS ::before or ::after pseudo-elements with symbols is more your style.

Bonus Points?

Just in case someone was wondering how images and other links within a heading is parsed into an id...

- [Imaged](#alt-textbadge__examplehttpsexamplecom-to-somewhere)


## [![Alt Text][badge__example]](https://example.com) To Somewhere


[badge__example]:
  https://img.shields.io/badge/Left-Right-success.svg?labelColor=brown&logo=stackexchange
  "Eeak a mouse!"

Caveats

MarkDown rendering differs from place to place, so things like...

## methodName([options]) => <code>Promise</code>

... on GitHub will have an element with id such as...

id="methodnameoptions--promise"

... where as vanilla sanitation would result in an id of...

id="methodnameoptions-codepromisecode"

... meaning that writing or compiling MarkDown files from templates either requires targeting one way of slugifeing, or adding configurations and scripted logic for the various clever ways that places like to clean the heading's text.

Experimenting, I found a solution using <div…/> but an obvious solution is to place your own anchor point in the page wherever you like, thus:

<a name="abcde">

before and

</a>

after the line you want to "link" to. Then a markdown link like:

[link text](#abcde)

anywhere in the document takes you there.

The <div…/> solution inserts a "dummy" division just to add the id property, and this is potentially disruptive to the page structure, but the <a name="abcde"/> solution ought to be quite innocuous.

(PS: It might be OK to put the anchor in the line you wish to link to, as follows:

## <a name="head1">Heading One</a>

but this depends on how Markdown treats this. I note, for example, the Stack Overflow answer formatter is happy with this!)

There is no such directive in the Markdown spec. Sorry.

Github automatically parses anchor tags out of your headers. So you can do the following:

[Custom foo description](#foo)

# Foo

In the above case, the Foo header has generated an anchor tag with the name foo

Note: just one # for all heading sizes, no space between # and anchor name, anchor tag names must be lowercase, and delimited by dashes if multi-word.

[click on this link](#my-multi-word-header)

### My Multi Word Header

Update

Works out of the box with pandoc too.

Since MultiMarkdown was mentioned as an option in comments.

In MultiMarkdown the syntax for an internal link is simple.

For any heading in the document simply give the heading name in this format [heading][] to create an internal link.

Read more here: MultiMarkdown-5 Cross-references.

Cross-References

An oft-requested feature was the ability to have Markdown automatically handle within-document links as easily as it handled external links. To this aim, I added the ability to interpret [Some Text][] as a cross-link, if a header named “Some Text” exists.

As an example, [Metadata][] will take you to # Metadata (or any of ## Metadata, ### Metadata, #### Metadata, ##### Metadata, ###### Metadata).

Alternatively, you can include an optional label of your choosing to help disambiguate cases where multiple headers have the same title:

### Overview [MultiMarkdownOverview] ##

This allows you to use [MultiMarkdownOverview] to refer to this section specifically, and not another section named Overview. This works with atx- or settext-style headers.

If you have already defined an anchor using the same id that is used by a header, then the defined anchor takes precedence.

In addition to headers within the document, you can provide labels for images and tables which can then be used for cross-references as well.

The pandoc manual explains how to link to your headers, using their identifier. I did not check support of this by other parsers, but it was reported that it does not work on github.

The identifier can be specified manually:

## my heading text {#mht}

Some normal text here,
including a [link to the header](#mht).

or you can use the auto-generated identifier (in this case #my-heading-text). Both are explained in detail in the pandoc manual.

NOTE: This only works when converting to HTML, LaTex, ConTeXt, Textile or AsciiDoc.