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

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?

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

Solution 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)

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

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