Consistent attribute syntax

Extensions
101

Just my 2pc on the concrete syntax: I would prefer

quote : mb21, post : 5, topic : 272

(with the spaces around : and after , probably optional) over

quote = mb21 post = 5 topic = 271

with or without spaces, for two reasons:

  1. It looks nicer (you can’t discuss about that, can you :wink:

  2. The “:” is easier to type than “=”, both on an US keyboard, and on the DE layout too (and I guess the same holds true for other layouts, because “:” is used more often than “=”). But then again, typing “{}” on a DE keyboard layout is a PITA already…

1 Like
102

I agree, @tin-pot, that aesthetics matter. Markdown isn’t HTML; a focus on readability is paramount. I wouldn’t require the spaces either, as this syntax feels natural:

quote: mb21, post: 5, topic: 272

But as an option, adding a space after each key looks fine as well:

quote : mb21, post : 5, topic : 272

1 Like
103

Let’s refine that just a bit:

  1. key: value pairs only (no id/class shorthands)
  2. : must be followed by at least one space
  3. unquoted # and = are not allowed

We now have a seemingly complete Inline YAML metadata extension proposal, which is accidentally compatible with the proposal that is the subject of this topic.

104

The draft proposal is very good, strongly defined and highly-compatible :relaxed:

I do have a couple of reservations, however, that I’d like to voice. I realize I’m slightly late to this party, but I didn’t see those raised above.

  1. Custom spans are an integral part of the Attributes extension, which means an implementation claiming compliance with the extension MUST support these. I believe they belong in a separate extension (perhaps one that is dependent on the Attributes extension).

  2. I find the spacing requirements inconsistent (and, in the case of list items, overly restrictive):

    • Inlines: no leading space.

      So far, so good.

    • Thematic breaks, headings, fenced code blocks and reference links: one or more leading spaces.

      Consistent with neither inlines nor fenced code class declarations.

    • List items: exactly as many leading spaces as the list markers.

      Is this a remnant from an old spec version that posed a similar restriction on list continuation?

I apologize in advance if any of these had been discussed.

105

How about adding indented code blocks? There seems to be a use case for that as well.

106

Totally voting this UP! I like the Markdown Extra way. Creating anchors and resizing images is essential. Being a Russian writer it is also very useful to set custom (non-auto-generated) ids to cope with any Unicode troubles while converting to HTML or LaTeX.

As for those who are afraid of HTMLness and “techyness”, you are not obliged to use those. To say even more, the fact that embedded images are not being visible in the text editor is already not so user-friendly or readable.

107

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="http://example.com/" target="_blank">Hello, world!</a>

This could be a sample implementing that target attribute:
[link]: http://path.to/link.html "Some Link" target="_blank"

108

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

109

@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

Ie:

- hello {id=1}

rather than

- hello
  {id=1}
110

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

111

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.

112

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

1 Like
113

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  |
114

Hey,

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

2 Likes
115

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

1 Like
116

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
117

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
118

Bjørn Erik Pedersen noreply@talk.commonmark.org
writes:

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.

119

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.

120

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?