In Markdown, what is the best way to link to a fragment of a page, i.e. #some_id?

Question

I'm trying to figure out how to reference another area of a page with Markdown. I can get it working if I add a

<div id="mylink" /> 

and for the link do:

[My link](#mylink)

But my guess is that there's some other way to do an in-page link in Markdown that doesn't involve the straight up div tag.

Any ideas?

Answer 1

See this answer.

In summary make a destination with

<a name="sometext"></a>

inserted anywhere in your markdown markup (for example in a header:

## heading<a name="headin"></a>

and link to it using the markdown linkage:

[This is the link text](#headin)

or

[some text](#sometext)

Don't use <div> -- this will mess up the layout for many renderers.

(I have changed id= to name= above. See this answer for the tedious explanation.)

Answer 2

I guess this depends on what you're using to generate html from your markdown. I noticed, that jekyll (it's used by gihub.io pages by default) automatically adds the id="" attribute to headings in the html it generates.

For example if you're markdown is

My header
---------

The resulting html will look like this:

<h2 id="my-header">My header</h2>

So you can link to it simply by [My link](#my-header)

Answer 3

With the PHP version of Markdown, you can also link headers to fragment identifiers within the page using a syntax like either of the following, as documented here

Header 1            {#header1}
========

## Header 2 ##      {#header2}

and then

[Link back to header 1](#header1)
[Link back to header 2](#header2)

Unfortunately this syntax is currently only supported for headers, but at least it could be useful for building a table of contents.

Answer 4

The destination anchor for a link in an HTML page may be any element with an id attribute. See Links on the W3C site. Here's a quote from the relevant section:

Destination anchors in HTML documents may be specified either by the A element (naming it with the name attribute), or by any other element (naming with the id attribute).

Markdown treats HTML as HTML (see Inline HTML), so you can create your fragment identifiers from any element you like. If, for example, you want to link to a paragraph, just wrap the paragraph in a paragraph tag, and include an id:

<p id="mylink">Lorem ipsum dolor sit amet...</p>

Then use your standard Markdown [My link](#mylink) to create a link to fragment anchor. This will help to keep your HTML clean, as there's no need for extra markup.

Answer 5

For anyone use Visual Studio Team Foundation Server (TFS) 2015, it really does not like embedded <a> or <div> elements, at least in headers. It also doesn't like emoji in headers either:

###  Configuration 

Lorem ipsum problem fixem.

Gets translated to:

<h3 id="-configuration-"> Configuration </h3>
<p>Lorem ipsum problem fixem.</p>

And so links should either use that id (which breaks this and other preview extensions in Visual Studio), or remove the emoji:

Here's [how to setup](#-configuration-) // Configuration 
Here's [how to setup](#configuration) //Configuration

Where the latter version works both online in TFS and in the markdown preview of Visual Studio.

Answer 6

In Pandoc Markdown you can set anchors on arbitrary spans inside a paragraph using syntax [span]{#anchor}, e.g.:

Paragraph, containing [arbitrary text]{#mylink}.

And then reference it as usual: [My link](#mylink).

If you want to reference a whole paragraph then the most straightforward way is to add an empty span right in the beginning of the paragraph:

[]{#mylink}
Paragraph text.