Sorely confused about "Extensions"

Extensions
1

What are extensions?

  1. Extra syntax supported by some other software than the C/javascript implementation hosted here?
  2. Proposed additions to the spec?
  3. Firefox/chrome like “extra software” than can be added to the C/javascript implementation hosted here?

I’m hoping for 3. Is there a plan for a generic extension mechanism? E.g. I haven’t found any description on how to write extensions in C or javascript.

We have a few itches of our own for using CommonMark for writing documentation:

  • Definition lists
  • Internal links
    Allowing us somehow to convert (something similar to)
    bug[App crashes when user hits Enter](CM-2345)
    into
    < href="http://our-jira-host.internal/browse/CM-2345">App crashes when user hits Enter</a>

Something like “Definition lists” would be great for lots of people so OK, maybe we’ll wait and see if it makes it into the spec and implementation at some point. But “Internal links” cannot make it into the spec, as they cannot be standardized.

Are there any plans to make it possible to extend the CommonMark implementation with custom extensions or what does this “Extensions” help category cover?

Quite confused…

2

The second option - proposed extensions to the CommonMark spec.

cmark and commonMark.js are reference implementations, however there are other implementations of the CommonMark spec such as markdown-it.

An implementation could implement just the core spec or the core plus some of the extensions. How the implementation does that is up to the implementer. It could be via plugins, flags that can be toggled, or the extension syntax could always be enabled.

Currently the focus is on completing the core spec, with extensions coming later.

2 Likes
3

Thanks @chrisalley, for your reply.

Lets call extending the spec “extensions” and dynamically loadable modules that implement extensions “addons”.

I’m a little disappointed, since I was hoping for addons.

Again, this means: Implemention what is in the spec now, and then everybody agreeing on an extended spec and the core team or trusted committers implementing that. Everybody gets exactly the same supported syntax.

Are there any plans for a way for individuals to be able to implement addons to extend CommonMark without having to fork, edit, configure, make and package?

If that were done, in a similar fashion to e.g. browsers, wordpress, jenkins, you-name-it, then we’d all be free to hack our own extensions (I could write my bug link above).

How would e.g. github be able to use CommonMark if they need the markup #3434 to point to issue number 3434? And now I’m writing this in Discourse, I notice Discourse uses this non-standard markup:

[quote="chrisalley, post:2, topic:1872"]
Currently the focus is on completing the core spec, with extensions coming later.
[/quote]

Super-handy. In order to do any of these with CommonMark, I’d also have to fork the project? Not super flexible.

Dynamically loadable addons could also reduce the pressure on including stuff in Core CommonMark if one could say: Core contains this only. If somebody wants the foobar extension, point to an addon and say, here, install this, and you’re good to go.

Oh, well, I’m sure you’re doing what is best. And I realize I have no idea about the complexity of the AST.

4

I think the extension point for your bug tracker syntax would be bogus URL schemes, e.g. [App crashes](bug://CM-2345). These could be handled easily by either a pre-processor or a post-processor or by a custom plugin to your CM parser. I’m not quite sure how I would like Discourse to extend the existing quote syntax using the > line prefix, maybe something like this:

> Currently the focus is on completing the core spec,
> with extensions coming later
-- [chrisalley](topic:1872#2)

It wouldn’t make much sense to limit the discussion here to addons for the reference implementations. Since CM tries to standardize MD it makes sense to also try to match third-party extensions as much as possible, not invent yet another syntax. The extensions in many flavors are actually quite compatible – on the surface at least, they may differ in the ugly details.

2 Likes
5

Ha, that is almost exactly how I was thinking of suggesting support for the <cite> element (maybe three dashes), do you know if this is already proposed or being discussed?

6

Hello, discussion about 3. can be found at https://github.com/jgm/cmark/issues/100 , warning that’s a huge thread, if you’re just looking for the initial implementation have a look at https://github.com/MathieuDuponchelle/cmark/commits/extensions_draft_3 , I try to keep that fork up to date with master but I wouldn’t mind merging it with the main branch at some point in the near future.

There are two example extensions in there, tables and strikethrough, and some more in my API documentation project, hotdoc, in this folder : https://github.com/hotdoc/hotdoc/tree/master/hotdoc/parsers . Please feel free to chime in in this thread about the proposed design, I will open a proper pull request once we come to an agreement about the interface.