Generic directives/plugins syntax


Should similarity to HTML be the goal here? Markdown was designed to be easy to read, in direct contrast to HTML which isn’t particular easy for a non-developer to understand. The use of HTML seems like a fallback in the original spec. For other parts of the Markdown syntax, the syntax choice appears to be in opposition to HTML.

It’s worth asking why colons were chosen for some languages instead of equals signs. In particular YAML. As with Markdown, YAML was designed to be human readable first and foremost. Have a look at part of this example YAML document from Wikipedia:

receipt:     Oz-Ware Purchase Invoice
date:        2012-08-06
    given:   Dorothy
    family:  Gale

The syntax is quite readable to a human, spaced out with key/value pairs seperated as you might expect a list to be written down. Also, the colon is used in English to express “this is what I mean” whereas an equals sign is typically used to express something mathematical. E.g. John Gruber created a language: Markdown.


That sounds reasonable. Good point about YAML and the usual meaning of : vs =. Still think we can do without commas (fine if commas is optional).

What do you think about this:

!audio[ title ]( url ){ size:10 duration:10 cycle:forever }


In YAML’s (JSON like) stream context, the advantage of using comma as item separators is that it allows omission of quotation marks in many cases, even when a value contains spaces. But YAML would require a space after the colons, unless the values were quoted.

So a more YAML like attribute notation might be:

{ title: some audio ambiance, cycle: forever }


It’s not the computer parser that concerns me, but the human parser. Whenever you add a second way to say something, readers are going to wonder what the distinction means. Remember, this is already a slightly esoteric region for non-programmers and not all Markdown flavors support it. So there will be some situations where folks will see a bit of line noise{id: “line-noise”, title = ‘$#@^(’ .extreme_example_to_prove_a_point} in their documents. If sometimes authors use = and other times : with optional commas and quotations and so on, it will make the problem exponentially worse.

Note: I’m a Perl programmer, so I’m used to reading cartoon character swearing. As a programmer, I like the flexibility. As someone who needs to explain Markdown to non-technical people sometimes, I dread it. So let’s pick one syntax and stick to it.

Since Markdown has close ties to HTML, we should prefer HTML attribute syntax.


I’m with jericson on this.


I’m in favour of this syntax. It’s a lot more readable (for an English writer) than the HTML attribute syntax, and readability should be emphasised above similarity to HTML. Especially if the goal here is the eliminate the need to use/know HTML.

I’m with @jericson that a singular syntax is preferable.


Yea I’m convinced on the readability argument, but at the condition that , is optional (Since , is mostly redundant, used to resolve ambiguities that can be solved via using ".

No commas (more readable since each “block” in {} is one attribute:

 { title:"some audio ambiance" cycle:forever }

With Commas (is more conventional):

 { title: some audio ambiance, cycle: forever }


Should the keys be allowed to contain spaces?


{ fontcolor: "light green" fontsize: 14 }


{ font color: light green, font size: 14 }

Not the best example (CSS would be better here), however from a readability point of view the example with a space in the key is easier on the eyes. The seperation seems to require the use of a comma though. Otherwise you’d need to specify it as something like this:

{ "font color": "light green" "font size": 14 }

Non-programmers aren’t going to understand the need for quotes (at least not without explaining it), so I’m in favour of commas for that reason.


Good point. Haven’t thought of it in that sense. It won’t look like HTML, and it’s not exactly json. But it does look like markdown in terms of visual simplicity.

I would say that "" would be included as an option, and this mode would allow for 'escaping characters. Without it, it would be read directly character by character (or as a number if numerical).


{ font color: light green}
{ string: string with \n new line }
{ string: "string with \n new line"}
{ number: 10 }


1. 'font color' = 
                  'light green'

2. string = 
                  'string with \n new line'

3. string = 
                  "string with 
                   new line"

4. number =


I hope we all agree that the directives’ {} should have the same syntax as the generic attributes. Since both MarkdownExtra and Pandoc have used {key=val key2="val 2"} for ages, I’m strongly in favour of sticking to that.

The inevitable "MarkdownExtra" topic

Could we do this the same way that other characters are escaped in Markdown? I’m just thinking of what would be most consistent for the writer.

It makes sense to use the same syntax for both generic directives and attributes.

I’m in favour of making extension syntax as close the philosophy of the original Markdown as possible. That may mean improving syntax.

CommonMark is about formalising Markdown syntax, but should the use of syntax in other implementations (beyond the original) be the primary reason for choosing that syntax? You could always convert MultiMarkdown/MarkdownExtra/Pandoc files to a new CommonMark extension syntax if needed.


This syntax would also help a lot while converting to non-html. My specific usecase is moving away from texinfo and be able to generate readable manpages.

Currently the best I found is kramdown-man (even if the man conversion lacks support for definition lists for now).


Thanks for the feedback. Btw, have you tried using Pandoc to generate man-pages?


pandoc had been considered and had been rejected since it is too heavy dependencies wise.

Currently we are using a custom set of perl scripts based on texi2html e texi2pod.

Ideally for the man page only perl, python and ruby would be ok. Or at least more likely to be accepted.


Yes, if those implementations are already widely used (which both of those are) - the point is to achieve a pragmatic spec using what is more or less common practice already.


@@@ is a bit hard for eyes on everyday use, it takes too many attention. Also note, that not all users, who have to use markdown, are programmers. I’d sugggest this format for block-style markup:

!!:name <anything, used as params>
... content ...

Example 1:

!!:spoiler Click me to expand

Example 2:

!!:float left

Block name is mandatory, params can have any format and processed by block code after name recognized.

In general, that have no principle differences with discussed above. Only a bit more eye-friendly look, and assumption, that params should not have strict form, only recommendations for complex cases.


If we use ! for block directives, then for consistency sake we would end up needing to treat generic directives as

!name[content](arg){#myId .myClass key=val key2="val 2"}

to maintain consistency with

!!!name[content](arg){#myId .myClass key=val key2="val 2"}
... content ...

With block directive shorthand

!!!spoiler "Click me to expand"
... content ...

is same as saying 

!!!spoiler[Click me to expand]
... content ...

This is plausible, as long as we treat ![](){} as shorthand for !image[](){}. Which would invoke the handler for embedding images in html.

  • I’ve suggested !!: block start prefix as more readable
  • Not sure, that it’s good idea to search consistensy between blocks of different nature.
    • blocks with preprocessor calls should be good for developpers and can have complex params
    • blocks with message elements styles (spoiler, sidebar, notice), are for ordinary users and must be readable and natural. Things like this name[content](arg){#myId .myClass key=val key2="val 2"} for ordinary user are total mess :slight_smile:


Don’t like !!: , potentially confusing. Plus is inconsistent with ‘code fencing’ syntax in CommonMark, which is visually similar.

Don’t see how that’s any harder to use. You don’t have to have all () [] {} elements since !nameOfExt is the base trigger word. You only need to add elements as you need, much like how english has core based words that are used often, and a person will learn many more vocabularies to handle edge cases. Thus for your examples it would be like:

!spoiler[ Click me to expand ]( Hidden text here )
!sidebarElement[ home ]( #home )
!notice[ This is an official notice to everyone ]{ .noticeclass }

If you need syntactic sugar, here is some extension to the above syntax for notice extension. Only supports strings however.

!notice:"This is an official notice to everyone" { .noticeclass }

alternatively without : (Omitting noticeclass class as well):

!notice "This is an official notice to everyone"

No recommended due to potential edge case, when wanting to use extensions without arguments.
      !randomQuote "this is not part of !randomQuote"

tl;dr: It is flexible enough for both block and inline. Can consider !name: " ... " or !name " ... " as an optional alternative to !name[] for natural message .


I hear you. But don’t underatand why block syntax should be consistent with fences. It should be readable first. And i don’t understand why “” should be used. Why not just pass the rest of string to block parser? If block needs ()[], it can split internally.

Also note, there is no practical need to make the same syntax between multiline blocks and inlines. In terms of html, i mean difference between display:block and display:inline. Blocks have to allow nesting. Inlines - not sure. Since cases do not intersect, each can have it’s own syntax, based on readability criteria. Everyting i suggested was only about multiline blocks.