Consistent attribute syntax


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


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

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


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


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


#81

@mofosyne since there’s no element to attach attributes to, this seems more a problem for a directive.


#82

Seems rather messy to use generic directives. How would you write slides for a slideshow presentation and style each differently? ( Imagine that ---- means make a new slide ). But doing it in a visually nice way.

# Presentation Title

---

# List
1. thing1
2. thing2

---    

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

#83

True, in such a case I would recommend using (for example) Pandoc’s --section-divs option which does:

Wrap sections in <div> tags (or <section> tags in HTML5), and attach identifiers to the enclosing <div> (or <section>) rather than the header itself.

Then you can style them by targeting the generated identifier.


#84

Would it work to do this? This uses ----- rules that you would see, when writing slides for slideshows

---
class: slideTitle 

# Presentation Title

---
class: slideInspirationalQuote

> Lorem Ipsum - The Quote

---
class: slideList 

# List
1. thing1
2. thing2

---  

This ties into my proposal for metadata attributes

The metadata is placed in attribute of the div tag for that section. As seen in the example Metadata in documents .


#85

For slides specifically, there are some good Markdown-based tools like remark. For a general solution to styling arbitrary-sized sections (without resorting to HTML), we could use a modification of the proposed span syntax, using square brackets.

The currently proposed way to insert span elements in text is using the following inline notation:

This is a sentence, and [this part is inside a span]{class=some-class}
You can see a larger example in previous posts

This could be extended to wrapping things in div elements when the brackets operate on a block level, perhaps like so:

[
    This is all inside of a div. [This is inside a span, inside the same
    div.]{class=styled}

    > This is a blockquote.
    > Still a blockquote.

    1. And now a list:
    2. See how these are all different blocks?

    ```
    If the indentation seen here was part of the syntax, then the parser would have
    to make sure to remove that leading whitespace when parsing other elements.
    This code block, for example, should not be rendered with the leading
    whitespace.
      Except for this line, which would be indented relative to the fence.
    ```
]{class=styled data-slide-number=3}

I indented it for readability – in my opinion it looks better, but an argument could be made either way. The indentation could actually be part of the syntax, to help reduce ambiguity.

A quick set of rules:

A div wrapper is applied when the following is true:

  1. A line starts with a single opening square bracket, followed by no other non-whitespace characters.
  2. The following line contains at least one non-whitespace character.
  3. All the lines between the brackets are indented. (Optional? Discuss.)

It would then be closed by a single ] character occupying its own line.

What do you guys think?

Edit: General fixes and corrections


#86

Argument could be made that indents are annoying. How about

[[[

non indented paragraph

]]]{ .styled slideNumber=3 }

still not quite as elegant as slide divider as ----


Btw my initial example is based off remark’s example http://gnab.github.io/remark/#11 which suggest this. I like this approach of having section attributes being defined in YAML.:

---
name: agenda
class: middle, center

# Agenda
The name of this slide is {{ name }}.

---

#87

What about the following, as a div syntax)?

::: { .styled slideNumber=3 }
one paragraph

another paragraph
:::

#88

For the record, I believe that completely hijacking essentially any use of ASCII braces for the attribute syntax is misguided. Maruku/kramdown had it right by requiring the colon; that is a combination much less likely to occur in running text. Markdown should err on the side of keeping simple things simple, and having to escape any brace is not simple.