Guide for syntax extensions

Spec
1

There are many markdown extensions out there. I’m wondering if it’s worth, as an appendix to the spec, for the authors of the spec to write a guide for choosing the syntax of extensions. This section could capture things that aren’t in the spec like:

  • Characters and/or constructs that should be considered reserved for a possible future addition to this spec
  • Thoughts by the authors on what sort of syntax could be used to introduce new inline or block features
  • Patterns for syntax extensions

For example, let’s say someone wants to implement an extension that renders a table of contents. Would something like @toc@, or %toc%, work as a block element? Or is that likely to conflict with other known extensions or possible future additions to the spec?

Another example is an extension we use for the Play Framework documentation that pulls in code snippets from external files (so that the code snippets can be compiled/run/tested), it’s a block element similar to the image syntax:

@[snippetlabel](path/to/code.scala)

This is a possible pattern that could be repeated for many different types of extensions that refer to external resources, and if the authors of the spec think this is a good pattern, of prefixing a link with a special character like this, then perhaps it’s worth mentioning it.

5 Likes
3

I’m just connecting a couple dots here - but this topic seems to relate to the suggestion that it woud be worth discussing how best to include simple extensibility points for extensions.

As the core spec “settles”, the extensions will remain of keen interest to many, I’m confident.

4

It certainly does, and I didn’t notice that topic before.

I’m not sure whether this topic should be considered a duplicate of that, or whether it should be considered the fulfilment of Jeff’s suggestion to:

create a topic about how best to include simple extensibility points for extensions, ways to namespace them and handle order so they don’t conflict, etcetera.

5

The latter! The heading is clear, as is the focus. (IMO, FWIW, etc.)

6

I’d like to suggest that the directive syntax from reStructuredText 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.

7

My issue with that syntax is it doesn’t feel very markdown-like, it would look a bit out of place in a markdown document.

1 Like
8

Have you got a better idea?

9

I might have: created a new thread in the Extensions category.

10

This thread is probably the same as this link. If so, please merge discussion to link below.

http://talk.commonmark.org/t/generic-directives-plugins-syntax

FYI: This is what we got so far:

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

@@@name[content](arg){#myId .myClass key=val key2="val 2"}
      \*Content to pass to extension*\
@@@

Edit: Thank’s Codinghorror!

1 Like