How to link to part of the same document in Markdown?

Question

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

Answer 1

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.

Answer 2

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.

Answer 3

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)

Answer 4

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

Answer 5

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>

Answer 6

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