Add "plugin" syntax to the spec

Spec
#1

It would be useful to have standard syntax to identify a “plugin”.

This would allow parsers & renderers to perform additional behavior (if they support it).

Perhaps something like the shortcodes in Hugo: http://hugo.spf13.com/extras/shortcodes/

Eg:

{{% youtube 09jf3ow9jfw %}}

Would generate appropriate HTML to generate an embedded Youtube link for HTML output but something else for some other output target.

Another example:

{{% figure src="/media/spf13.jpg" title="Steve Francia" %}}

to generate a properly formatted figure.

The spec could cover the basic plugin syntax and what happens when the plugin is not supported etc…

2 Likes
Optional syntax
Generic directives/plugins syntax
Extension terminology and rules
#2

This is part of the more general concept of “markdown extensions”.

Your definition of “plugin” is unnecessarily strict, in my opinion.

There shouldn’t need to be just one “plugin syntax”.

I would want to see something like this:

This Markdown Extension adds Hugo Shortcodes.

A shortcode is an inline element, and is parsed inside of both block and inline HTML.

A shortcode begins with two opening braces …

There’s some discussion over here about extensions:

http://talk.commonmark.org/t/the-inevitable-markdownextra-topic/42/14

My contribution to the topic is basically reproduced above - basically stating that extensions should have specs similar to the Standard Markdown spec.

#3

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”.
4 Likes
#4

This could be merged to this thread about general directives

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

Currently this is what we got:

For media extension (Which is what I think your examples is pointing towards)

!mediaType[description](url){#myId .myClass key=val key2="val 2"}

e.g. For your youtube example with youtube id 09jf3ow9jfw :

!youtube[](https://www.youtube.com/watch?v=09jf3ow9jfw){ #id .class width=100px height=100px }
  • 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*\
@@@
#5

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 =/

1 Like