Consistent attribute syntax

I totally agree with the suggested spec already.

For completeness, here another (important) use case - open links (e.g. PDFs) in a separate window:
<a href="" target="_blank">Hello, world!</a>

This could be a sample implementing that target attribute:
[link]: "Some Link" target="_blank"

Consistent attribute syntax is not on the list of issues to resolve before CommonMark 1.0, so I’ve moved this topic over to “Extensions”.

@mb21 did anything happen with your pull request? I hate replying to a message that’s more than 2 years old.

I just wanted to point out my preference for being able to add an attribute to a list item via the inline syntax, which I see your pull request for the spec doesn’t include


- hello {id=1}

rather than

- hello

I think this should rather be a conversation on adding meta attributes to markdown than all of this focus on html attributes

I think for todo lists, GitHub task list items are visually and intuitively cleaner solution.

* [ ] open (undone) task item
* [x] closed (done) task item
* [X] closed (done) task item

To change done/undone status only requires changing one character and in all cases the markdown source tends to reflect the fact that it is a task item.

In my implementation I made GitHub task items an optional extension, rendered as:

Without it these render as:

Which still conveys them as task items.

There’s a topic discussing their implementation as a seperate CommonMark extension.

1 Like

Has anyone thought about how this would apply to tables? E.g. In psv, I’ve been thinking about how would I add self validating tables, e.g. a simple form of a table schema.

Would I still have to wrap a json payload in quote? Or would json be recognised as a value payload? Or is there a better way? Or is this beyond the scope?

{#tableID schema={"First Header": "string", "Second Header": "string" } }
| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |


I’m developing a static site generator named Hugo. We use a Markdown parser/renderer called Blackfriday which is mostly CommonMark compliant.

I have thought about the problem in this thread. A lot. Often when I think of a new useful feature in Hugo, I’m either blocked by this – or I have to create some ugly workaround.

I have read this and other threads about this. The objections I see are of type “this is too coupled to HTML/formatting”. I think we need to think beyond just CSS classes. What I really need is

  • a way to add “processing tokens” to a node in the document
  • my own namespace that I can use as I please for my custom processing instructions
  • I guess it would also be natural to create a reserved namespace for CSS classes and possibly some other

My current “cool thing I want to do with Markdown in Hugo” is to allow people to tell Hugo how to process images:

![alt text](/my-image.jpg "Logo Title Text 1") {: hugo:Fill:"300x300" }

Or whatever. The above example is probably not the best, but there are many situations in the world of publishing where you need to pass on some instructions to the renderer. And the “you can use HTML” really doesn’t solve these problems (when the target isn’t even HTML).


Hey @bep! For the use-case you mention, we have had this working in pandoc for quite some time…

1 Like

I could probably “get something working” with Blackfriday, too. But the reason I reach out on this forum is to get this into some common spec so “all” parsers would recognize this pattern. Given the image processing example above, I would expect GitHub to just throw away that instruction and display the image as-is.

1 Like

to get this into some common spec so “all” parsers would recognize this pattern.

Totally agreed, that’s the goal of this thread. Unfortunately, commonmark hasn’t reached 1.0 yet, so this is going to take some time. All I’m saying is that if you’re going to implement something like that, following pandoc’s precedent might lead to fewer headaches when it comes to standardizing this in commonmark. I might, of course be biased…

1 Like

Bjørn Erik Pedersen

I could probably “get something working” with Blackfriday, too. But the reason I reach out on this forum is to get this into some common spec so “all” parsers would recognize this pattern. Given the image processing example above, I would expect GitHub to just throw away that instruction and display the image as-is.

Currently your best bet might be to use actual HTML
processing instructions.

![My image](img.png)<?hugo:size=300?>

The special instruction will be ignored by GitHub
(actually it will be changed into an HTML comment, it
appears), but you could look for it in the AST and
modify the image rendering accordingly.

Not a beautiful solution, but it could be
something to consider, and it works right now.

Having read the discussion up to this point, I would propose to not add an attribute syntax that just passes its argument through to HTML. Instead I propose to only include attributes in the specification that actually add value on top of what could be achieved with HTML or LaTeX.

My particular use-case, coming from Support for image dimensions, is to have the equivalent of LaTeX’s \includegraphics[width=0.9\textwidth]{file} and to be able to render that into PDF / LaTeX in the same manner as it would be rendered into HTML. Without such an attribute the rendering engine has an impossible task: It cannot automatically decide whether an image should be up/down-scaled or included 1:1 just by looking at the image and the output format.

I agree that forcing more specific sizes, like width=500px height=20px, is out of scope for CommonMark and better left to specialised HTML or LaTeX syntax.

In addition to the above, I would suggest to not conflate the use of IDs (technical implementation) with the need for anchors and links (HTML) or labels and references (LaTeX). Labels and references to them are very much useful when writing any larger document, while I would agree that having control over HTML IDs and HTML classes might be out of scope for Markdown. How labels and references are being rendered into the final document should be the decision of the processor, depending on the desired output (HTML or PDF / LaTeX), while CommonMark should only concern itself with their abstract concept.

And it has the advantage of being ignored by Markdown renderers which don’t have consistent attribute syntax enabled. Even if GitHub never adopts consistent attribute syntax, you’d still have the advantage of an HTML comment being hidden in a GitHub readme. If not everyone wants to adopt the extension, perhaps this even a preferable 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?

1 Like

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

1 Like

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

1 Like