Anchors in markdown

mofosyne · September 4, 2014, 8:39am

Right now there is no markdown anchor syntax. Simplified anchor syntax would be handy when you want to make a hypertext fiction (or a more complex documentation). Current approach is to just type in the html code for anchors. For example in this half baked idea post.

According to http://stackoverflow.com/questions/484719/html-anchors-with-name-or-id anchor is defined by html #id . Thus:

Perhaps it can be a modified version of the link syntax

[anchorName] {#anchorName}

Alternatively you could restrict it to headers like

header text here
========================= {#anchorName}

or

#  header text here # {#anchorName}

Elsewhere in the document you can create a jump point to the anchor like

[test](#anchorName)

Edit: Modified to fit what other people are suggesting for generic attribute syntax

Sherjil_Ozair · September 4, 2014, 9:05am

I would like to add that Markdown is used often for one-page webpages, where anchor links become very important, if you want to send out detailed links. So it would be great of Standard Markdown to make the common case nicer.

lightblade · September 4, 2014, 3:18pm

This is a much needed feature that only exist in very few markdown implementation.

mb21 · September 4, 2014, 3:36pm

I agree and propose that this should be seen in light of the issue of a generic attribute syntax. Therefore, # Header here {#anchorName} might be preferred (as already implemented in Pandoc).

jericson · September 4, 2014, 6:18pm

This would be a very useful addition for authors. But there are some difficulties in implentation. Notably, duplicate ids in the DOM might cause problems. I also prefer the Markdown Extra syntax:

# header text here {#anchorName}

mofosyne · September 5, 2014, 5:49am

I think that looks much better jericson so good idea, if it allows for jumping to that anchor.

tabatkins · September 5, 2014, 8:47pm

Notably, duplicate ids in the DOM might cause problems.

No, duplicate IDs make your document non-conforming, but don’t actually cause any problems. (At least, no problems with the browser. If you’ve got a script that thinks an id is a unique identifier, it might get the wrong element when it tries to retrieve an element by ID, but that’s it.)

jericson · September 5, 2014, 9:58pm

Sure. But it seems like a bad idea to introduce a feature that doesn’t work reliably. As with Wikipedia, the big concern is to allow unambiguous links to sections of a document. There is likely no perfect solution, however.

ConnorKrammer · September 8, 2014, 2:13am

This has enough uses and adds little enough in the way of syntactic complexity that I believe its inclusion in core CommonMark is reasonable.

I tend towards making it a modified form of the link syntax, since anchor links are links, and because it would allow anchoring to any location in a document, not just to a limited number of elements. (I believe that Markdown Extra doesn’t allow arbitrary placement of anchor links, though I may be wrong.) That said, I wouldn’t be against a standard syntax that allows the setting of arbitrary attributes on an inline or block element, which would serve the same purpose but allow greater flexibility.

That said, in the end I have the feeling that this is going to be deemed “extension material” and left for other people to implement.

mofosyne · September 8, 2014, 3:11am

For anchors, this is starting to come towards the proposed standard for a generic attribute syntax via {} for example:

 ![altText](myImage.png){#id .myClass width=40 height=50}

So in the case of anchors, it would just be a case of setting the #id tag of an element. E.g.

 []{#id}

 [Optional Anchor Text]{#id}
 
 # Header with anchor # {#id}

 Header with anchor
 =================== {#id}

I modified my first post to fit this development

http://talk.commonmark.org/t/consistent-attribute-syntax/272

We maybe could merge this thread with

http://talk.commonmark.org/t/consistent-attribute-syntax

mb21 · September 8, 2014, 9:35pm

Yes, so [content]{#id} would render as <span id="id">content</span>.

jgm · January 7, 2015, 5:26am

See also this related thread: Turning empty link definitions into anchors

just_dmitry · June 9, 2016, 2:27pm

No, please do not merge this topic with http://talk.commonmark.org/t/consistent-attribute-syntax

This are completely different things.

Additional attributes are presentation-level bells and whistles - classes for different styling, image sizes, custom attributes… This can be additional extensions to spec - no problem.

But anchors (this topic) should be part of spec core. Part of links. Why spec allow me to make link to other page/doc, but doesn’t allow to link to other place in same doc?

a-raccoon · August 26, 2016, 6:06am

I’m very sad to see this thread hasn’t moved in 2 years. I feel this is an absolute essential core element of markdown that should supersede all other consideration right now. Markdown simply cannot be used in any serious document format without the ability to set and reference anchors for use table of contents, chapter indexes, bibliographic and footnote references… you name it. Every single document format ever created, from richtext to word, hlp to chm, from epub to mobi, and 99 other ebook and document formats, all have an anchor naming and linking system in place.

Markdown is the absolute singular contender yet to enter the arena.

chrisalley · August 26, 2016, 8:05am

Anchors for headers have been discussed quite extensively in the Automatically generated IDs for headers topic.

a-raccoon · August 26, 2016, 4:48pm

Thanks for the link! Btw, I’m not sure that headers are the only place for anchors.

Michael_Pacer · December 22, 2016, 12:03am

tldr; There is absolute consensus that manual header id assignment is an important feature for CommonMark and its absence is a weakness of the spec. There is general consensus that the syntax that best fits this use case is a {#anchor-id} following the definition of the header. All the contentious issues that have held it up do not actually apply to manual header id generation. How can this move forward?

Consensus syntax:

# Header example {#Anchor-id}

To create

<h1 id="Anchor-id"> Header example </h1>

Estimates of consensus:

This thread

Of 16 posts on this thread 11 speak positively of this syntax or the importance of a solution. 4 of the remaining do not address the merits of the syntax or the solution. 1 states that the problem is likely to have no perfect solution.

Automatic id generation thread

Of 84 posts on the Automatically generated IDs for headers topic, 15 speak positively of the {# } syntax & of the importance of having a solution.

There are three other syntax styles proposed, which have 4, 2 and 1 post in favour of each of them which have 2, 1, and 1 proponent (respectively). Of posts in which other syntaxes are proposed, these all included mention of the more general attribute assignment problem. Of those individuals favouring other syntaxes, 1 of the 2 proponents of the 4 post syntax later agreed that the {#anchor} syntax is better, on the grounds that it is already present in pandoc.

The rest of the posts (62) do not explicitly discuss the syntax or need for manual anchor ids focusing on the main issue of that other thread (how to automatically generate ids).

Conclusion: Consensus has been reached, progress has been arrested by scope creep

Having analyzed this thread as well as the discussion at Automatically generated IDs for headers topic, it’s seems that the correct next move is to proceed toward implementing the {# } for manually specifying ids for atx headers.

The discussion began 2 years ago, and it should not need to continue longer before this feature is included in the spec.

There universal consensus that allowing manual ids on headers is an important feature and a assured improvement to the CommonMark spec.

There is widespread (but not universal) consensus on the use of the {# } syntax for manual header id assignment. Of posts that comment on syntaxes, 79% support this syntax, over 6× the level of support for any other syntax.

Addressing Dissent: Manual header ids are not objects of dissent

All of dissent in these threads seems to revolve around whether this should be a more general way of assigning attributes and whether there should be auto-generated header ids.

These concerns don’t need to block progress manually specified header ids. This approach to including header ids leaves open the possibility of autogenerating them (but says nothing about autogeneration one way or the other). Additionally, it allows for other syntaxes (as well as an expansion of the same syntax) as a means of assigning attributes to headers.

Steps forward?

@jgm and @codinghorror, what are the next steps needed to see progress on this? Happy to put in the effort wherever it is needed.

jgm · December 23, 2016, 7:08pm

I agree that this is a good syntax. It’s already widely supported (e.g. in pandoc). I think the main questions are:

Since this is really an extension, should it wait til we’ve got the existing core nailed down, or should we just plow ahead?
Should this be thought of as a special case of a more general attribute specifier? In pandoc you can have {#identifier .class .other-class key="value"}. Of course we could also support the simple identifier form for now and leave the others for later.

chrisalley · December 24, 2016, 4:01am

Plow ahead with this being the first extension. It’s been two years and the distraction could prove to be a refreshing break from dealing with edge cases in the core. Plus lots of people have been asking for a way to add anchors, and manual header ID generation is relatively simple (compared to, say, tables). Automatic header ID generation could be considered later.

It would make sense to group these together. #id for IDs and .class for classes is intuitive. key="value" could be key: "value" or key: value and look a bit less “programmerish” so it’s less obvious to me what the best syntax is here.

Crissov · December 25, 2016, 2:22am

There are lots of subtle syntax variants that most people would also accept, but which may score better at compatibility. Several ones of them could be supported, others forbidden. Some alternatives play better with info strings of fenced code blocks, others with current or proposed link syntax.

Meta data inside curly braces

## Heading {#ID .class}
## Heading ## {#ID .class}
## Heading {#ID .class} ##
## {#ID .class} Heading
{#ID .class} ## Heading
{#ID .class}
## Heading
{#ID .class}
## Heading ##
## Heading
{#ID .class}
## Heading ##
{#ID .class}
Heading {#ID .class}
-------
{#ID .class} Heading
-------
Heading
------- {#ID .class}
Heading
{#ID .class} -------

Meta data (only) separated by line affix

## Heading ## #ID .class
#ID .class ## Heading ##
#ID .class ## Heading
#ID ## Heading ## .class
.class ## Heading ## #ID
Heading
------- #ID .class

I’m probably forgetting some possibilities and proposals.