# Guide for syntax extensions

**URL:** <https://talk.commonmark.org/t/guide-for-syntax-extensions/193>\
**Category:** Spec\
**Created:** [September 4, 2014, 1:57am UTC](https://talk.commonmark.org/t/guide-for-syntax-extensions/193 "2014-09-04T01:57:25Z")\
**Posts on this page:** 1\
**Showing post:** 6

<div class="post-metadata">

**Author:** ![zwol](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/zwol/32/63_2.png) [@zwol](https://talk.commonmark.org/u/zwol)\
**Post date:** [September 4, 2014, 3:39pm UTC](https://talk.commonmark.org/t/guide-for-syntax-extensions/193/6 "2014-09-04T15:39:36Z")

</div>

I’d like to suggest that the [directive syntax from reStructuredText](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#directives) be considered as a generic block-level extension syntax. It’s straightforward, if a little verbose, and is unlikely to conflict with anything. It looks like this:

```
.. directive-name:: [positional arguments]
   [ :key1: value1 
     :key2: value2
     ... ]

   [text content, one or more paragraphs]

```

All arguments are optional; if there is “text content”, it must be set off by a blank line; everything after the `.. directive-name::` line that’s supposed to count as part of the directive must be indented at least three spaces. (For Markdown purposes, I would suggest that laziness is allowed to apply to text content as for paragraphs within list items, but _not_ key-value arguments.)

reST also has an inline-extension syntax, `:role:`text`` but I’m less fond of it.

---

_[View the full topic](https://talk.commonmark.org/t/guide-for-syntax-extensions/193)._