Markdown syntax for roles and directives

Last week we had a few nice conversations around “how to extend Markdown to support roles and directives from Sphinx”.

This is a quick issue to try an keep track of our thinking there.

What kinds syntax chunks are there?

• operate on raw text and yield a block element
• operate on raw text and yield an inline element
• operate on commonmark block content and yield a block element
• operate on commonmark inline content and yield an inline element

What we arrived at

After a few conversations, we arrived at a syntax that uses triple-backticks, followed by directive name, followed by configuration with two options (either using {key=val} or YAML front-matter inside the code block).

So something like (ignore the slashes, just for rendering purposes):

\```mydirective {key=val}
\```

And for in-line text, using single-backticks followed by an identifier in the traits associated w/ it:

This is `my role`{myrolename key=val}

This effectively treats everything as “raw text”, with the idea that this would degrade gracefully by just rendering as a raw blob if the directive didn’t exist.

How would this clash with current markdown or rST behavior?

Something like this:

• If a triple-backtick block is found, check the language associated with it
• See if the language exists in a list of directives in the current environment
  • If so, treat it as a directive block and not a language block. Anything in {} becomes configuration for the directive. Anything inside the backticks becomes content that is processed by the directive.
  • If not, treat it as a language block

Something similar could be done with in-line blocks

What others have found

• here is a good thread describing how pandoc approaches this
• here is how autostructify handles it
• here is a nice proposal for how to do this in commonmark

[choldgraf]

[chrisjsewell]

Behold the first Markdown directive parser!

See the bottom of https://github.com/chrisjsewell/mistletoe/blob/myst/test.ipynb

Current format is:

````{note}
abcd *abc* [a](link)

```{warning}
xyz
```

````

which is transformed to docutils AST:

<document source="">
    <note>
        <paragraph>
            abcd 
            <emphasis>
                abc
             
            <pending_xref refdomain="True" refexplicit="True" reftarget="link" reftype="any" refwarn="True">
                <reference refuri="link">
                    a
        <warning>
            <paragraph>
                xyz

FYI for all the tests (which are extensive) see: https://travis-ci.org/chrisjsewell/mistletoe