My contribution to the topic is basically reproduced above - basically stating that extensions should have specs similar to the Standard Markdown spec.
This is definitely something Rust’s documentation system Rustdoc would like to see in one form or another. We’ve been considering a migration to reStructuredText due to Markdown’s poor standardization, and lack of extensibility. However we prefer markdown for its popularity and simplicity (we want writing docs to be super accessible). Standard Markdown of course resolves the former issue, so having a solution to the latter would be highly desirable!
In particular, we’re interested in being able to write the following extensions:
Mathjax support: adds a new inline and block element with similar semantics to the inline and block code elements that mathjax can correctly handle on the clientside
“Relative” header levels for embedding markdown fragments. That is, # foo isn’t an <h1>, but rather an <h(1 + base_level)>.
Special known sections to be handled differently. Unclear at what level this would be exposed. Just a css class that gets added to be styled/selected on? Or extra metadata returned with the parse to be further used by the caller?
Custom link types. In our case we’d like to be able to say something to the effect of “link to the function/struct/module with this name”.
The mediaType is youtube, so use extension for dealing with youtube links, and to handle the parameters passed in {} (After #id.class is extracted from {} )
For general extensions (e.g. scientific python parsers, for evaluating snippets of python)
@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*\
@@@
I’m evaluating CommonMark for the same purpose but for Libav documentation and probably you’ll have the same issue I have regarding supporting manpages as output.
right now {: .attribute}, an include clause and table support is more or less all I need (and I could find in kramdown already).
Currently my experiment with wiring commonmark-py in docutils show promising results already =)
And yes, reSTructuredText is sadly not accessible enough =/