Multiple levels of CommonMark specification?

[mofosyne]

One way to structure different editions of CommonMark is this:

Specification Levels:

CommomMark Barebone, Core, and Extended comes as both a specification and an implementation. Only CommonMark draft comes as a specification sheet only (as a wiki?). Anything written in a lower number specification can be rendered in a higher number.

1. CommonMark Barebone := The most minimalistic specification. Designed to be most computationally efficient. Uses only the most commonly used markups. E.g. Here is a tiny implementation of markdown: micromarkdown

2. CommonMark Core := Is considered the base standard. This will cover 80% of all use cases. If an extension is used in too many CommonMark Extended package editions, then it should probably be in core.

3. CommonMark Extended := Most complete officially implemented specifications theoretically. It is a set of packages, aimed at different audiences with a mix of extensions relevant to a field. Examples shown below:

• Scholar :~ Supports extensions often requested in academia like Figure tags
• Film Script :~ Stuff useful for those storybording or film scripting
• Coder :~ Stuff useful for programmers documentation
• Etc… you get the point.

4. CommonMark Draft := This specs is like the ‘w3 draft specification’ sheets. It is not implemented anywhere, but is there to be revised over and over again by the community (via a wiki?) until it is ready to be implemented in CommonMark Extended. (But at the very least, it will lets other implementers know ahead of time how to write their semi-fork. E.g. the moz- prefix for HTML/CSS specification drafts in firefox)

• Perhaps every month, the wiki is generated as a pdf and stamped with a version number, so that people can say they are compliant to CommonMark Draft V2.XX etc… for non officially supported implementation.

Fail Gracefully

In html specification. A key philosophy is to fail gracefully. So for CommonMark, if you render using a lower implementation, it should still come out as legible writing. This comes though writing higher order syntaxes carefully in such a way that it can fall back into other forms of rendering in lower levels, that will come out as aesthetically and contently pleasing enough.

e.g. !youtube[Cat Video](https://www.youtube.com/watch?v=dQw4w9WgXcQ) will gracefully die like this " !youtubeCat Video ". Where the older parser will still parse []()

---

Originally from http://talk.commonmark.org/t/optional-syntax/

[mofosyne]

The idea is that this structure would help address the concerns that no one syntax would make everyone happy. This is by focusing on a very minimal core specification, and then branching out multiple ‘package mix’ of extensions for every specific use cases.

John Gruber (gruber)

Thus the anarchist, and order faction of both CommonMark and markdown would be satisfied.

In theory.

[chrisalley]

I hope we can simplify this. I suggest just two types of configurations:

1. Markdown Core
2. Markdown Core + a set of official CommonMark extensions (of your choice)

If a feature is used, but the extension isn’t implemented, it would fall back to the Markdown Core interpretation. So long as we design the extensions not to conflict with one another, is there an issue?

[robinheydon]

I think the key to success is to have a single “specification” document. However, this document describes the set of core functionality required to be considered compatible with CommonMark and it also includes additional sections (say section 7 and beyond) that describe officially defined extensions.

The key to this approach is that each of these extensions would include the appropriate test cases, and an implementation could then clearly state which extensions they support.

I might even suggest that there is some section up front (perhaps a new 1.4) that describes the core and extension concept and also states that compatible means.

“Compatibility with the core means that an implementation passes all the test cases within this specification (as defined by section 1.3). Compatibility with an extension means that an implementation passes all the test cases within that extension whilst at the same time also passing all the core test cases.”

[mofosyne]

While extensions must conform and not interfere with core specification, can different extensions interfere with each other?

If John Gruber is correct, it will be impossible to have a full commonmark that can cover all use cases.

Maybe extensions interfering with each other is inevitable, but at the very least we can group extensions together like coder, academic, law, etc… and mandate that within each group it must work together, but it is not as much of an issue (tho discouraged) to interfere with other extensions in other group. (e.g. An extension syntax for coder may interfere with film script)

[chrisalley]

We should aim to make extension syntax not conflict with other extension syntax so that any extensions can be mixed together. This should be possible, provided we keep the number of extensions small. I think this can be achieved by reusing syntax, e.g. create a syntax for a generic block element and allow classes to be applied to it for different purposes such as ‘spoiler’, ‘warning’, etc.

[robinheydon]

I don’t think extensions should conflict with each other. In fact, I think you should be able to build an implementation that passes the core specification and all the extensions enabled at the same time.

And I don’t think requires us to keep the number of extensions small. They just need to be very well thought out and considered.

[Alamo]

I think, this spec only define the core rules, then others could add extensions based on the core rules

For example, localization. Local community is able to develop new extensions based on their own languages, culture, writing habit… to make markdown more compatible and easier to use for local people.