Consistent attribute syntax


Just for the record, markdown-it and a number of other implementations converts the < to &lt;.



Howdy folks :wave:

I have been using a custom syntax for attributes for code-blocks for quite some time now in a reasonably large app and I’m interested in making it “more standard”. Is this the right place to chip in with the discussion? Are there any regular meetings where things are planned?

Also, I don’t just want to reply to this thread with a “this is the way that I would like it to look” I’m more interested in helping to shepherd any specification through than making sure it’s my personal preference of the syntax :joy:


Yes, I believe it is. You could describe a syntax and invite other people here to share their thoughts.

Keep in mind, there’s already some variation (or is it fragmentation?) in attribute syntax among different Markdown flavors and other writing formats like Markua. For example…

Pandoc / PHP Markdown Extra / Earlier version of CommonMark spec:

{#myId .myClass key=val key2="val 2"}

Maruku / Kramdown:

{:ref-name: #myid .my-class}


{key_one: value1, key_two: value_two, key_three: "value three!", key_four: true, key_five: 0, key_six: 3.14}


Since Markdown supports, and indeed encourages more than one way of marking up elements, I think it would be fine to support some or all of these variations. Both key: value and key=value are logically equivalent, and the #id and .class syntax acts as a useful shortcut. So long as they’re within curly braces, I don’t think there should be any issue with parsers supporting a mixture of attribute syntax?


Ok cool :+1:

The syntax that we’re utilising is similar to the one you mention is in the “Earlier version of CommonMark”:

```handlebars {data-filename="app/templates/components/rental-listing.hbs" data-diff="-15,+16"}

This comes from the Ember Documentation here to allow us to render filename and diffs:

As for the syntax, I wonder if we can’t potentially aim for having something a lot simpler in the spec? :thinking: I understand the benefits that people might have about using shortcuts for ids and classes but I wonder what is wrong with the simpler to define:

```hr {id="awesome-rule" class="blue" data-unrelated="all the data"}

I am not familiar yet with the CommonMark spec process but I wonder if a simpler definition of a feature is much more likely to make it through?

And yes I agree with @chrisalley that because of the multiple markup situations we could support both key: value and key="value" (and maybe even key=value but I am less bothered about that).


We’ll probably need to wrap multi-word values within quotes, e.g. key="multi word value" or key: "multi word value", but single word values could leave off the quotes, e.g. key=value or key: value.

I think we should use double quotes around the value, so that the writer can use values that contain apostrophes, e.g. thought-experiment: "Schrödinger's cat"

Since there may be cases where values contain double quotes, we could alternatively support wrapping the value in single quotes, e.g. key: 'my "useful" value'.


I thought I had said this earlier, but since I cannot find it, I will mention it possibly again: The implementations of equals vs. colon syntax for key-value pairs differ in that the latter requires a comma (or perhaps semicolon) between pairs, thus it does not need quote marks. Also, the equals sign is usually directly attached to the key and the (possibly quoted) value, without intervening whitespace, whereas the colon is almost always followed (and possibly preceded) by whitespace.


I like it the idea of leaving off quote marks. But it does raise the question of what happens when there is a colon or comma inside of the value string. What does this produce?

title: Horizon: Zero Dawn

It seems to me that a value containing a colon or comma would be more common than the value that contains double quotes.

Markua requires that multi-word value strings are wrapped in double quotes. I wouldn’t mind staying close to the Markua rules. This would also keep the = and : quote rules consistent. There would be less cognitive overhead switching between the two.

If we wanted to take consistency to the next level we could make the commas between the key/value pairs optional. That way, any of the following four would be valid:

{key_one: value1 key_two: value_two key_three: "value three!" key_four: true key_five: 0 key_six: 3.14}
{key_one: value1, key_two: value_two, key_three: "value three!", key_four: true, key_five: 0, key_six: 3.14}
{key_one=value1 key_two=value_two key_three="value three!" key_four=true key_five=0 key_six=3.14}
{key_one=value1, key_two=value_two, key_three="value three!", key_four=true, key_five=0, key_six=3.14}

The parser could simply ignore the commas, leaving it up to the writer to optionally include them for aesthetic purposes.