New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Colon in Attributes List Definitions needed? #176

Closed
mb21 opened this Issue Oct 16, 2014 · 7 comments

Comments

Projects
None yet
3 participants
@mb21
Copy link

mb21 commented Oct 16, 2014

In an effort to expand on CommonMark, we've discussed generic attributes and I've come up with a proposal for an extended spec. Any feedback is welcome.

Kramdown supports attributes on a lot of elements with {: key=val} and I understand that the colon is needed when declaring and using a set of attributes separately. However, it isn't when you don't use references. So I was wondering whether you would consider making the colon (:) optional in order to make the {key=val} syntax universal across Kramdown, Pandoc and Markdown Extra.

@gettalong

This comment has been minimized.

Copy link
Owner

gettalong commented Oct 16, 2014

The colon after the opening brace has two functions:

  • It differentiates an IAL from an ALD.
  • The two characters together are not likely to appear in existing documents.

The second point is important so that documents that have been written with another Markdown variant can more easily (and correctly) be converted with kramdown.

Since changing this syntax would probably break existing documents, this is a no-go for 1.0.

Also note that kramdown implements IALs for all elements whereas PHP Markdown Extra implements a similar syntax only for headers, fenced code blocks, links, and images and Pandoc only for headers. So this is not really a good reason to change the syntax on kramdown's side.

@gettalong gettalong closed this Oct 16, 2014

@mb21

This comment has been minimized.

Copy link

mb21 commented Oct 17, 2014

I see that this is a no-go for 1.0. But would you agree for 2.0? About the points your raised:

  1. If I understand correctly, IALs (Inline Attribute Lists) look like {: .my-class}, and ALDs (Attribute List Definitions) like {:ref-name: .my-class}. So I don't see the problem of allowing both {: .my-class} and {.my-class} for IALs.
  2. It's true that not requiring the colon increased the probability of clashes slightly (although it would still need to contain either .myClass, #myId or someKey=someVal—otherwise the whole attribute list would be parsed as normal text). However, I believe that the simplicity is worth the risk.

In addition to headers, Pandoc also has attributes on fenced code blocks and inline code spans. But yes, Kramdown is certainly further along with attributes. That's why I appreciate your feedback.

@gettalong

This comment has been minimized.

Copy link
Owner

gettalong commented Oct 17, 2014

I don't know when I will release a 2.0 version (will certainly not be in the next 6 months) but if there is a general consensus and many implementations follow, I will also consider the change. If this is a thing of one implementation, there is no real benefit in changing the syntax.

@mb21

This comment has been minimized.

Copy link

mb21 commented Oct 17, 2014

That's great to hear. Currently CommonMark is still focussed on the basic/core Markdown, but I've been going ahead with the proposal because I'd like to see a consensus around a generic attribute syntax.

Since Kramdown would only have to make the colon optional, the change should even be backwards-compatible to existing Kramdown documents with attributes (as long as they haven't normal text that clashes with the syntax).

@shicks

This comment has been minimized.

Copy link

shicks commented Oct 26, 2016

Is it possible to reconsider this? This is an important incompatibility between Kramdown and several other Markdown engines, and if there were a consensus then CommonMark could possibly make progress on actually standardizing it.

@shicks

This comment has been minimized.

Copy link

shicks commented Oct 26, 2016

Note also that it's not just the colon that's different - it's the placement as well. Kramdown expects the IAL to precede the element it affects, whereas Pandoc, HoExtDown, and Markdown Extra expect their attribute lists to follow the heading/code block.

@gettalong

This comment has been minimized.

Copy link
Owner

gettalong commented Oct 27, 2016

@shicks IALs in kramdown can be placed before and after a block level element.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment