Consistent attribute syntax

Extensions
61

I don’t intend this in any way to denigrate any individual person, but if we allow the syntax to specify something as ridiculously complex as ![altText](myImage.png){.myClass width=40 height=50} then CommonMark has completely failed its mission.

If you honestly need syntax that complex, just use HTML. Use-cases like this are exactly why Markdown has the ability to fallback to HTML.

This is practically impenetrable:

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

Compared to just writing it in HTML:

<img src="myImage.png" class="myClass" width="40" height="50" alt="altText" />
2 Likes
62

That’s not an option for those of us using Markdown to export to other formats like TeX as well.

Also, as I said above:

Finally, Kramdown, Pandoc and MarkdownExtra already have some kind of attribute syntax and as described in the draft:

[Attributes] don’t need to be implemented to conform to this spec. However, if an implementation includes [attributes], this spec strongly recommends to implement the syntax described here.

P.S. Just discovered another use case:

Instead of:

[quote="mb21, post:1, topic:272"]
quoted text
[/quote]

which this forum currently uses for quoting other posts, we could use standardized attributes:

> quoted text
{quote=mb21 post=1 topic=272}

Which is more readable and markdown-like? My point is that there will always be people that want markdown with a little cusomized extra functionality (like e.g. in this forum). Attributes enable this in a uniform way that should soon be familiar to the more advanced users that need it (if it isn’t already) and will reduce the need for many custom extensions like the [quote][\/quote]-syntax (which I can’t seem to properly escape in an inline code span).

4 Likes
63

Great catch about quotes! I’m almost sold :slight_smile: . Need those for nodeca (btw, nodeca is one of the main reasons why i develop all my projects on github). Quotes were the only critical thing, that i could not fit into markdown without kludges, until seen you example.

If this syntax will have no collisions, seems i have to reconsider my top priorities for spec & remarkable.

3 Likes
64

Finally, Kramdown, Pandoc and MarkdownExtra already have some kind of attribute syntax

Then why not use those formats? If the CommonMark syntax doesn’t provide a sufficient level of complexity for you, then use one of the dozen other markup syntaxes available. I’m not sure why CommonMark has to be everything to everyone.

we could use standardized attributes

The only thing “standardized” in this proposal is the use of braces. The particular attributes allowed – and even whether they are allowed at all – will still be entirely dependent on where they are being used. This will lead to enormous confusion for users and conflicting implementations which is exactly what CommonMark was designed to mitigate.

I’m just very, very against this proposal in its current state; I think it pollutes the syntax and doesn’t add nearly enough gain for the problems it will introduce.

If you really truly desire this, then implement it in some parser that you need for your uses. And if you want to spread it, establish it as AttributedCommonMark or whatever you like. But it does not belong in the CommonMark standard in its current state.

65

Because commonmark let us having the data in a format that possibly could be used across the languages instead of having to be careful on which implementation has the feature you need.

Attribute blocks/inline blocks are a commonly missed feature and works quite well for most usecases.

lu

1 Like
66

To @nexussays,

This brings to mind, it would be good to have a consistent way to use this syntax for certain applications. E.g. That spoiler class should always be spelled .spoiler . Or that intersite quotes should have a certain consistent attribute names as well.

Examples so far that can do well with attribute syntax & recommended usage case:

  1. Quoting

     > quoted text
 {quote=mb21 post=1 topic=272}

  2. Spoilers

     Spoiler text
 As a block
 {.spoiler}

 This is an [ inline spoiler yo ]{.spoiler}

  3. code

     ````````````````
 print(1+2)
 ````````````````
 {.python author=joe package=mathPy }

 ` print("hellowworld") `{.python}

I know that usually for codes it’s:

    ```````````````` {.python author=joe package=mathPy }
    print(1+2)
    ````````````````

I think it can still be supported for short {}. But best practices should be this instead. Since its more manageable for long attributions. E.g. in R notebook format, the {} is used to store environment settings for the code block.

    ````````````````
    print(1+2)
    ````````````````
    {.python author=joe package=mathPy }
67

I would prefer the block above I think its less intrusive

{quote=mb21 post=1 topic=272}
> quoted text

From a spec perspective this is a bit tricky, as this would map to say:

<blockquote data-quote="mb21" data-post="1" data-topic="272"><p>quoted text</p></blockquote>

So we are defining that { always appends data- which is ok, but how would you add standard attribs like say class?

Also would you support {quote="mb21"} and {quote='mb21'} ?

68

Meta before quote will seriously conflict with previus content.

May be, on the first quote line?

> {quote=mb21 post=1 topic=272}
> quoted text
69

That works, I think its stronger semantically cause its very clear that the meta belongs to the quote, though… how would you enter

> {test}

Perhaps:

>! quote=test post=1

Then you can retain

> !

As it has a space there

70

(Hey, I’m back!)

This is all getting fairly specific, now. I think it’s important that there aren’t too many edge cases for specific elements–this particular spec is intended for power users, but it shouldn’t be unfeasible for, say, someone just learning HTML/CSS to pick up quickly. The more deviations from a generalized syntax there are, the more nightmarish it all becomes. I’d very strongly recommend keeping the metadata at the end of the element for this reason.

@sam, on the data- prefix front, it’s worth mentioning the work the fine folks over at AMCSS are doing. They don’t use “data” as a prefix at all, since support for arbitrary attributes is almost universal (read what they say on the topic, however–they know their reasons better than I do). In the case of quote, I’m inclined to just have the user type out “data-quote” if that’s what they want the output to be. There isn’t really any need to add a processing step between what the user types and what it actually turns into. From a user-experience point of view, more steps means higher mental load and more confusion.

As for the

> {test}

use case, I don’t think this is really an issue. I can’t think of a reason why anyone would need to render an empty block quote with nothing but metadata attached to it, so the spec would state that you can’t have such an element (thereby solving the ambiguous case). Again though, I very much think we should be careful not to stray too far from a standard syntax. How would you explain to a user that metadata on a paragraph is entered in curly braces on the line following, while metadata on a block quote is entered within the quote on the first line while preceded by an exclamation mark, without curly braces? It all seems terribly arbitrary. Let strange derivative syntaxes belong to other implementations–CommonMark is for intuitive, standard solutions.

71

I agree with @ConnorKrammer that users should write { data-quote=test } if they want the data- prefix. The attributes are general key-value pairs that are not specific to HTML.

Yes, see the first post in this topic, which I sometimes update with new developments.

I can see that some people would prefer the attribute block above the quotes… but I’m not sure it’s a good idea to add two ways (above and below) to place an attribute block.

@sam, note that:

> paragraph
> {.test}

already stands for attributes on the paragraph:

<blockquote>
  <p class="test">paragraph</p>
</blockquote>
72

I agree that attributes should always be placed below content that it styles. This is since light markup syntaxes in general are all about content first over flexible markups. Attributes in front of content is just distracting.

1 Like
73

Some points:

  • Kramdown uses {: } , dropping the : might not be a great idea.
  • As for the ATXHeader, being strict with the spaces might be a good idea so { attribute="value"} might work as well as {:attribute="value"} and {: attribute="value"}.
  • Placing this block only above or only below might be a good idea, surely having it in the middle is not so great so

``

``` { .python}
def  fun():
     pass
```

Would be mildly irregular.

74

@lu_zero

  • I think the colon in {: } should be optional since it’s only really needed to reference kramdown’s Attribute List Definitions. I raised this as a kramdown issue and it seems he’s sympathetic to making that change for a 2.0 release.
  • as described in the draft, spaces inside the {} are permitted but don’t change the semantics.
  • for better or worse, the “block in the middle” is already implemented for fenced code blocks in pandoc, kramdown and markdown extra.
1 Like
75

Then I guess we are set with it. Can it be part of core or be an extension?

76

What’s the actual purpose of the colon? Is that Kramdown-specific (I’m not familiar with the particulars of that implementation of Markdown), or would it make parsing easier?

77

it would make parsing easier and it is kramdown/maruku specific.

78

Then I suppose whether we include the colon syntax in the spec depends on a couple things:

  1. Are we willing to make this mandatory? If it’s optional, then the implementation benefit when parsers is lost since it will have to be implemented both ways, not just one.
  2. Does this have any other obvious benefit to users? One of the goals of CommonMark is to make a user-centric syntax, not a programmer-centric syntax. In other words, easy usage > easy implementation.

For the second point, an argument could be made in the other direction, depending on viewpoint: Does the improved parseability of the colon syntax make many more programmers likely to implement it, thus making it available to that many more users? In other words, we’re now discussing the trade-off between a loss of elegance (using the point of view that more characters = more distraction = less elegance) and a possible boost in how many spec-conforming implementations there are.

I’ve never implemented a Markdown parser personally (though I have worked with them and modded them before), so it would be nice if someone with a bit more experience than me could chime in with their opinion on that last front. I’m willing to be swayed either way, though if we do decide to support the colon syntax I think it should be mandatory, to avoid just adding work for implementers (not to mention complicating the user’s mental model of Markdown).

2 Likes
79

I agree that the colon shouldn’t be in the spec. The probability of clashes is reduced only slightly and it’s by far more complicated to remember and type.

If the proposal (see above) is adopted into CommonMark (e.g. as an extension), I think Kramdown should make the colon optional in their implementation. That way they remain compatible with older Kramdown files, as well as with this syntax. If Kramdown is to implement a strict CommonMark-mode, the colon shouldn’t be allowed there at all.

2 Likes
80

Btw how would I apply a specific style to all text below header 2 only. Also what if the header were ------ horizontal ruling instead?

# header 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 

# header 2

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

# Header 3

Etc...

This is needed if we are do use this for applications of slideshow writing, where you want to style a specific slide.