Add support for anchor links

[adam-p]

See discussion here: https://groups.google.com/forum/?fromgroups=#!topic/markdown-here/eaq1JoNhyws

[adam-p]

Can probably be done by hacking this line in marked.js to be name instead of id. Or... perhaps name in addition to id, so we remain HTML5 compatible and maybe work better in non-email places.

[adam-p]

I took a look at this and... it's not as easy as I'd hoped (mostly because I hadn't thought it through properly).

First of all, the id --> name hack I mentioned in my previous comment isn't sufficient. A header element with an id can be used as an anchor link target, but name doesn't work. So I'd have to change marked.js to add an <a href="#" name="my-anchor"></a> element for each header element. That doesn't make me super happy, but I can't see that it'd break anything.

So, anchor link --> anchor target is certainly doable, if a little dirty. The bigger problem is the usability of it.

The simplest thing to do would be to rely on what Marked is already doing to transform (let's say slugify) the header text when adding IDs -- it's lowercasing and replacing adjacent non-alphanumerics ([^\w] aka [^A-Za-z0-9_]) with a dash. So ## My Header: Sweet becomes <h2 id="my-header-sweet">My Header: Sweet</h2>. As as user, you'd write:

[Jump to where my header is sweet](#my-header-sweet-yes-experts-tell-us)
...
## My Header: Sweet? Yes -- experts tell us
...

That workflow isn't terrible, but it means that users have to mentally do the slugification in order to create their anchor links. That's not easy for everyone.

And it's complicated by another unfortunate thing: It's not possible to test your anchor links. At least not in Gmail -- if you click a rendered anchor link, you get Gmail's little link-editor box pop up, and if you then click the "go to link" link it opens a new tab with your Gmail inbox (technically, it opens a new tab with current-url + #myanchor).

Well, that's a bad combination: a difficult-to-guess slugification combined with an inability to (reasonably) test your guess.

@caseywatts foresaw this when he first requested the feature (and I subsequently, foolishly, didn't fully appreciate this):

We could probably come up with an easy enough syntax where a link like [linkname](#Name Of Section) would convert to a dash-separated sting or something, and link to #Name Of Section. The reverse of whatever the Marked.js convention would be.

I didn't, and don't, really like this, since it's a (/another) deviation from the Markdown spec (and the HTML spec, kinda). Spaces are valid characters in links but they have to be escaped (%20). You can have then inside the href attribute of a link and they get convert automatically when you click on it (for me, in Chrome). Try clicking these two links: [http://example.com/ima space/](http://example.com/ima space/) and http://example.com/ima%20space/ -- you end up on a page with the same URL (the latter, escaped). Works the same for in-page anchor links.

If we made this change, it would break this (entirely valid MD, which someone might be writing right now):

[jump 1](#MyJumpy)
...
<a href="#" name="MyJumpy"></a>
...
[jump 2](#Another Jump)
...
<a href="#" name="Another Jump"></a>

Because, with the change, it would render to this:

<a href="#myjumpy">jump 1</a>
...
<a href="#" name="MyJumpy"></a>
...
<a href="#another-jump">jump 2</a>
...
<a href="#" name="Another Jump"></a>

...which breaks the anchor links. (However, if the jumps go to headers and the anchor links used the exact text of the headers, then it would work, because they'd get slugified the same. But I don't think that's likely enough to save us.)

What to do?

It could be made optional. There's nothing wrong with this, but I don't really like it. I think it'll be difficult to coherently describe to the user what the option does. And it seems like a usability cop-out. But it can be done. (Default on? Default off?)

Or we could just make the change and let people complain if it causes them a problem. I'm leaning towards this.

I'd appreciate any input anyone might have. I'm going to let this simmer for a little bit.

[adam-p]

Implemented in 83aa9c4. Will be in the next release (which will be soon).

@caseywatts: If you can try it out, please do. Thanks.

[caseywatts]

I'm so excited for this! ^_^

I'll gladly test it out, thanks!
On Oct 4, 2013 10:39 PM, "Adam Pritchard" notifications@github.com wrote:

Implemented in 83aa9c483aa9c4.
Will be in the next release (which will be soon).

@caseywatts https://github.com/caseywatts: If you can try it out,
please do. Thanks.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/93#issuecomment-25740599
.