Consistent attribute syntax

Extensions
94

Not sure which one is the easiest to implement or the more intuitive.

95

For what it’s worth, I think

> para
> {.attr}

is more intuitive. I find attributes on paragraphs a bit much though.

The alternative,

> para
{.attr}

implies to me that the attributes are on the blockquote.

I am also a fan of

> {.attr}
> blah blah

for attributes on blockquotes.

96

The latter is an attribute to the paragraph.

I started implementing that on CommonMark-py btw.

97

consider a todo list, with both completed and incomplete items.
This way the class of the li item can be used to control the icon (via css). Example vith one syntax from those mentioned above:

 - buy bread
 - buy milk {.done}
 - buy cheese
{.todo}
1 Like
98

Why not—at least for links to sections and subsections—refrain from eagerly uglifying the proper text syntax, and rely on the fact that very likely every section and subsection already has a distinguishing property: simply the header’s text!

One could use this property (concrete: the wording of the section’s header) in an extended kind of reference, maybe like that:

## Introduction to Mark-up ##

### Special cases ###

As we have seen in the [introduction](@intro...mark-up), the most common cases are already [...]

In other words: use a pattern to refer to a section where the header matches this pattern.

It would be the implementation’s job to derive consistent and acceptable id attributes (ie conforming to the HTML rsp XML requirements) for the generated header elements (like <H2>) and in the generated href attributes (of, say, <A>), of course.

Details are of course TBD, like in the example above to do case-folding while matching, or ignoring punctuation, or provide more advanced forms of patterns like glob or even regexp syntax (for the experts among the Markdown writers :wink:

I haven’t yet thought about linking to other elements however. Any ideas?

1 Like
99

@tin-pot, yes, this was already discussed at length here and has been implemented by e.g. pandoc. However, consistent attribute syntax solves a lot more problems.

2 Likes
100

Thanks for the pointers, I didn’t know about the existing discussion. Looks like the idea isn’t that far-fetched after all.

1 Like
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  |