# Generic directives/plugins syntax

**URL:** <https://talk.commonmark.org/t/generic-directives-plugins-syntax/444>\
**Category:** Extensions\
**Created:** [September 6, 2014, 9:50am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444 "2014-09-06T09:50:24Z")\
**Posts on this page:** 20\
**Page:** 8

<div class="post-metadata">

**Author:** ![nielsle](https://talk.commonmark.org/letter_avatar_proxy/v2/letter/n/35a633/32.png) [@nielsle](https://talk.commonmark.org/u/nielsle)\
**Post date:** [June 2, 2015, 1:13pm UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/141 "2015-06-02T13:13:35Z")

</div>

Wild idea. How about unifying code for plugins and code formatting. The average user cannot tell the difference anyway, so why bother.

```
~~~ youtube { vid=09jf3ow9jfw }
Here is a video of my cat. 
~~~

```

---

<div class="post-metadata">

**Author:** ![lu\_zero](https://talk.commonmark.org/user_avatar/talk.commonmark.org/lu_zero/32/557_2.png) [@lu\_zero](https://talk.commonmark.org/u/lu_zero)\
**Post date:** [June 2, 2015, 5:40pm UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/142 "2015-06-02T17:40:33Z")

</div>

The markup looks leaner and intuitive, I wonder how it would behave with other formatting needs (e.g. sphinx/docutils bridging).

---

<div class="post-metadata">

**Author:** ![jgm](https://talk.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [June 3, 2015, 9:04am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/143 "2015-06-03T09:04:51Z")

</div>

+++ nielsle [Jun 02 15 13:23]:

> [1]nielsle  
> June 2
> 
> Wild idea. How about unifying code for plugins and code formatting. The  
> average user cannot tell the difference anyway, so why bother.
> 
> ```youtube
> Here is a video of my cat.
> 
> ```

One advantage of this sort of approach is that requires no  
changes in the parser. You just need to go through the AST,  
looking for specially marked code blocks and transforming  
them to links or whatnot.

Compare my comment [here](http://talk.commonmark.org/t/what-could-a-spoiler-tag-extension-look-like/767/68).

---

<div class="post-metadata">

**Author:** ![Crissov](https://talk.commonmark.org/user_avatar/talk.commonmark.org/crissov/32/1455_2.png) [@Crissov](https://talk.commonmark.org/u/Crissov)\
**Post date:** [June 15, 2015, 11:37pm UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/144 "2015-06-15T23:37:42Z")

</div>

One nice thing about most lightweight markup languages is that they do not rely on English words for tag and attribute names or keyword values since they are repurposing ASCII punctuation/non-alphanumeric characters instead. All those extensions with key-value pairs and explicit names harm that principle. They are a step back. They are not based upon prior art, i.e. actual practice in plain-text media. They are not in the spirit of Markdown. They impose coder habits onto a general purpose language. They must be considered harmful. They are a bad idea.

That being said, there is a place for names that are not predefined, i.e. IDs and classes, or that are proper names, e.g. language names for automatic highlighting in code blocks. IDs can be auto-generated, however, in most if not all cases.

In other words, if you want verbose tags you have come to the wrong place and should use XML/HTML or (La)TeX instead.

---

<div class="post-metadata">

**Author:** ![jgm](https://talk.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [June 16, 2015, 12:34am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/145 "2015-06-16T00:34:16Z")

</div>

+++ Crissov [Jun 15 15 23:47]:

> One nice thing about most lightweight markup languages is that they do  
> not rely on English words for tag and attribute names or keyword values  
> since they are repurposing ASCII punctuation/non-alphanumeric  
> characters instead. All those extensions with key-value pairs and  
> explicit names harm that principle. They are a step back. They are not  
> based upon prior art, i.e. actual practice in plain-text media. They  
> are not in the spirit of Markdown. They impose coder habits onto a  
> general purpose language. They must be considered harmful. They are a  
> bad idea.

This is a real advantage of Markdown (and its ilk) over LaTeX, DocBook, HTML, etc. If you write in Swedish, your source document looks like Swedish – not Swedish with a bunch of English words mixed in. So I’m against hard-coding English words into the syntax.

Of course, going too far in the other direction makes your source document look like Perl.

---

<div class="post-metadata">

**Author:** ![mb21](https://talk.commonmark.org/user_avatar/talk.commonmark.org/mb21/32/162_2.png) [@mb21](https://talk.commonmark.org/u/mb21)\
**Post date:** [October 20, 2015, 8:22am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/146 "2015-10-20T08:22:58Z")

</div>

Just discovered and [played around](https://markdown-it.github.io/#md3=%7B%22source%22%3A%22%5BCustom%20containers%5D%28https%3A%2F%2Fgithub.com%2Fmarkdown-it%2Fmarkdown-it-container%29%5Cn%5Cn%3A%3A%3A%20warning%5Cn%2Ahere%20be%20dragons%2A%5Cn%3A%3A%3A%5Cn%5Cn%5Cn%3A%3A%3A%20foo%5Cnisn%27t%20this%20supposed%20to%20be%20a%20div%3F%5Cn%3A%3A%3A%5Cn%5Cn%3A%3A%3A%20warning%20%7B%23id-is-ignored%7D%5Cn%2Ahere%20be%20dragons%2A%5Cn%3A%3A%3A%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Atrue%2C%22typographer%22%3Atrue%2C%22_highlight%22%3Atrue%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22html%22%7D%7D) with @vitaly’s markdown-it container plugin which allows the most basic form of _3. Container Block Directives_ proposed [above](http://talk.commonmark.org/t/generic-directives-plugins-syntax/444). Pretty cool! Looking forward to hear your experiences when you’ve got more user feedback etc.

---

<div class="post-metadata">

**Author:** ![vitaly](https://talk.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\
**Post date:** [October 20, 2015, 8:39am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/147 "2015-10-20T08:39:15Z")

</div>

We use it for quotes & spoilers:

 ![](https://talk.commonmark.org/uploads/default/original/1X/aa3d5651c60ef88927dc09d7ab0c3846f9adf678.png)

Don’t be confused wit ``` syntax. That’s for convenience. It overrides defaults when keywords `quote` and `spoiler` used, and run our plugin to allow markup in internal content.

---

<div class="post-metadata">

**Author:** ![mb21](https://talk.commonmark.org/user_avatar/talk.commonmark.org/mb21/32/162_2.png) [@mb21](https://talk.commonmark.org/u/mb21)\
**Post date:** [October 20, 2015, 8:56am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/148 "2015-10-20T08:56:25Z")

</div>

I meant:

```
::: warning
here be dragons
:::

```

---

<div class="post-metadata">

**Author:** ![mofosyne](https://talk.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\
**Post date:** [October 20, 2015, 9:20am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/149 "2015-10-20T09:20:51Z")

</div>

Yup mb21, I would be interested to see how the custom container function in the wild. Seems to be fine so far.

What would you think of the **detail block** as a solution for spoiler blocks [w3schools page on the `<details>` tag](http://www.w3schools.com/tags/tag_details.asp)

```auto
^^^ classname summary text
full content here
^^^

```

```auto
<details>
  <summary>summary text</summary>
  <p> full content here </p>
</details>

```

* * *

e.g.

```auto
^^^ spoiler for harry potter ^^^
snape dies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

```

---

<div class="post-metadata">

**Author:** ![mb21](https://talk.commonmark.org/user_avatar/talk.commonmark.org/mb21/32/162_2.png) [@mb21](https://talk.commonmark.org/u/mb21)\
**Post date:** [October 20, 2015, 9:44am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/150 "2015-10-20T09:44:58Z")

</div>

Unfortunately, the `details` element [is not widely supported by browsers](http://caniuse.com/details).

---

<div class="post-metadata">

**Author:** ![mofosyne](https://talk.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\
**Post date:** [October 20, 2015, 9:48am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/151 "2015-10-20T09:48:29Z")

</div>

😕 then at least as a ‘detail’ block within commonmark, but expressed in html in whatever best way we can do for now (e.g. how we do spoiler text in html nowadays).

---

<div class="post-metadata">

**Author:** ![tin-pot](https://talk.commonmark.org/user_avatar/talk.commonmark.org/tin-pot/32/810_2.png) [@tin-pot](https://talk.commonmark.org/u/tin-pot)\
**Post date:** [October 27, 2015, 3:18pm UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/152 "2015-10-27T15:18:39Z")

</div>

There is no need for using a `<detail>` element which is already kind-of-defined in HTML, but may or may not be recognized by browsers and other HTML consumers: if the purpose (from the point of view of the _CommonMark_ processor) is to “wrap” an uninterpreted block of raw text (which is what I take from @mofosyne’s remark about “to see how the custom container function in the wild”), one better “invents” an element type name which does not conflict with popular DTDs like HTML.

This [works](https://github.com/tin-pot/cmark/blob/master/chain/cmark_filter.c#L203) already quite nicely for an element type called `<mark-up>` in my little project (not exactly “in the wild”, but we’ll go there): As the _CommonMark_ processor `cmark_filter` does now, so will other mark-up processors recognize and process this special “container element” type _only_, until it is vanished from the output document.

---

<div class="post-metadata">

**Author:** ![lu\_zero](https://talk.commonmark.org/user_avatar/talk.commonmark.org/lu_zero/32/557_2.png) [@lu\_zero](https://talk.commonmark.org/u/lu_zero)\
**Post date:** [November 3, 2015, 12:32am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/153 "2015-11-03T00:32:51Z")

</div>

Something along those lines is used also by recommonmark (e.g. to bridge rst-specific constructs that are too annoying to support natively)

---

<div class="post-metadata">

**Author:** ![tin-pot](https://talk.commonmark.org/user_avatar/talk.commonmark.org/tin-pot/32/810_2.png) [@tin-pot](https://talk.commonmark.org/u/tin-pot)\
**Post date:** [November 4, 2015, 7:19am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/154 "2015-11-04T07:19:29Z")

</div>

That’s an interesting key word you mentioned there: “_[recommonmark](https://recommonmark.readthedocs.org/en/latest/#)_”—so thank you for the hint!

Yes, that seems similar to the concept I’ve based my project on; but so far I only took a glimpse of the first page that popped out of the _Google_ search …

[The `rst` means _[reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText)_, if I understand correctly.]

---

<div class="post-metadata">

**Author:** ![lu\_zero](https://talk.commonmark.org/user_avatar/talk.commonmark.org/lu_zero/32/557_2.png) [@lu\_zero](https://talk.commonmark.org/u/lu_zero)\
**Post date:** [November 26, 2015, 7:13am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/155 "2015-11-26T07:13:52Z")

</div>

Exactly and probably this part should be agreed soon, since would be nice to be able to use it.

---

<div class="post-metadata">

**Author:** ![vdb](https://talk.commonmark.org/letter_avatar_proxy/v2/letter/v/c77e96/32.png) [@vdb](https://talk.commonmark.org/u/vdb)\
**Post date:** [February 17, 2016, 9:58pm UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/156 "2016-02-17T21:58:52Z")

</div>

> On the other side, I wouldn’t see any harm in allowing either colons : or equality signs = when specifying attributes, or allowing optional commas ,. The values on the right-hand side of a key-value pair shouldn’t contain either symbol and the additional overhead for parsers is minimal.

Markdown has some relations with HTML (e. g. it allows HTML code), so HTML attribute syntax is preferable.

I would like to specify attributes for RDFa. In such a case values _can_ have colons:

```
[tiger]{property=ov:preferredAnimal}

```

---

<div class="post-metadata">

**Author:** ![steveklabnik](https://talk.commonmark.org/user_avatar/talk.commonmark.org/steveklabnik/32/990_2.png) [@steveklabnik](https://talk.commonmark.org/u/steveklabnik)\
**Post date:** [June 28, 2016, 2:17pm UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/157 "2016-06-28T14:17:38Z")

</div>

It seems like this discussion has significantly stalled; is that right? I’m trying to research what the current state of extending Markdown is, and this thread seemed like the place. Is that true?

---

<div class="post-metadata">

**Author:** ![jkdev](https://talk.commonmark.org/letter_avatar_proxy/v2/letter/j/e79b87/32.png) [@jkdev](https://talk.commonmark.org/u/jkdev)\
**Post date:** [June 28, 2016, 9:19pm UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/158 "2016-06-28T21:19:16Z")

</div>

As I understand it, the priority right now is to get version 1.0 of the core CommonMark spec finalized before adding extensions. See [this thread about adding tables to CommonMark](https://talk.commonmark.org/t/tables-in-pure-markdown/81):

> [@Tables in pure Markdown](https://talk.commonmark.org/t/tables-in-pure-markdown/81/4):
>
> This is meant to be a specification of core markdown features. Extensions, including tables, can come later, but let’s get the core settled first!

---

<div class="post-metadata">

**Author:** ![amix](https://talk.commonmark.org/letter_avatar_proxy/v2/letter/a/c77e96/32.png) [@amix](https://talk.commonmark.org/u/amix)\
**Post date:** [September 5, 2019, 4:31pm UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/159 "2019-09-05T16:31:38Z")

</div>

> [@chrisalley](#):
>
> `!audio[title]( url ){ size: 10, duration: 10, cycle: forever }`
> 
> is more readable than:
> 
> `!audio[title]( url ){ size=10 duration=10 cycle=forever }`

That’s a _very_ subjective one 😉 I prefer the equal ‘`=`’ sign.

> [@mb21](#):
>
> Since both [MarkdownExtra](https://michelf.ca/projects/php-markdown/extra/#spe-attr) and [Pandoc](http://johnmacfarlane.net/pandoc/README.html#extension-header_attributes) have used `{key=val key2="val 2"}` for ages, I’m strongly in favour of sticking to that.

Good point!

If we’d use colons, I would leave out the empty space after the colon. It looks good on multline listings but not on a single line. It competes with the literal spaces, that belong to a sentence and, thus, creates line noise. I think, here, perception of the line is different as it is in source code, where I prefer spaces after most of the symbols.

But I can live with either. Though, for uniformity, we should settle on only _one_.

> [@mofosyne](#):
>
> 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 `"` .

I think the space " " itself creates ambiguity. Take programs, that let you add tags (to posts, etc.). This way I can not have spaces in them. Then I forget about it, assume a comma to be the seperator and bam! I have an unneeded tag.

Comma ‘`,`’ is what is used to list stuff, within a sentence, in literature. This is why we should be consequent about it. We also use them in arrays and in function signatures in programming. Empty space means separation of words, not items.

---

<div class="post-metadata">

**Author:** ![0alpha](https://talk.commonmark.org/user_avatar/talk.commonmark.org/0alpha/32/1836_2.png) [@0alpha](https://talk.commonmark.org/u/0alpha)\
**Post date:** [March 25, 2020, 7:30am UTC](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444/160 "2020-03-25T07:30:20Z")

</div>

Is there further progress on this, or is it stalled?

> [@amix](#):
>
> I think the space " " itself creates ambiguity. Take programs, that let you add tags (to posts, etc.). This way I can not have spaces in them. Then I forget about it, assume a comma to be the seperator and bam! I have an unneeded tag.
> 
> Comma ‘ `,` ’ is what is used to list stuff, within a sentence, in literature. This is why we should be consequent about it. We also use them in arrays and in function signatures in programming. Empty space means separation of words, not items.

On the other hand, spaces do have precedent for item separation. Shell is one, and Fish shell notably goes all in on this. The other notable (and relevant) example off the top of my head is HTML’s tag attributes.

As such, for consistency with HTML, I’m against commas.

[Previous page](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444.md?page=7)

[Next page](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444.md?page=9)
