When do you think we'll ship 1.0 of the CommonMark spec?

From my observation, the community here has rightly been focused on the concrete remaining blockers for a v1.0 of the CommonMark spec, via Issues we MUST resolve before 1.0 release [8 remaining] and related topics.

Rather than pollute that healthy focus, I wanted to start a separate topic to gauge the intuition of the various experts and community members here who have been working on this. This topic is here to also explicitly invite you to lean on the thinking fast, system 1 part of your brains.

I’ll update this post periodically with a new poll so we can capture the different collective sentiments at different points in time alongside each other. Feel free to elaborate on your answers in the comments below.

I’ll keep each poll open for 2 weeks.

When do you think we’ll ship 1.0 of the CommonMark spec?

Just, take your best guess; think fast and slow.

Sat April 28 - Sat May 12, 2018

  • Within the next 3 months
  • Between 3 and 6 months from now
  • Between 6 and 12 months from now
  • More than 1 year from now

0 voters

It’s entirely up to @jgm so I think there’s only one person we need to ask.

If some form of consensus is reached here, could this quote from the front page be updated? “we plan to announce a finalized 1.0 spec and test suite in 2017”


I went ahead and posted a PR to the website bumping the anticipated release: https://github.com/commonmark/web/pull/18

As time goes on, and the standardization effort loses steam, does it make any sense to make some concessions and just call it done, or make best-effort decisions on the remaining blockers, for the sake of signalling?

It’s been a while, and there are a number of implementations, and having a release would bring some excitement and long-awaiting closure to a major issue in the programming community.

Presumably there can be a CommonMark 1.1 if development steam picks up, which it well could after a big release.


@jgm could we move forward and promote the current 0.28 version of CommonMark as 1.0.0. I implemented markdig almost two years ago and the specs have been quite stable since then. Github Flavoured Markdown is now based on CommonMark as well with some extensions. Microsoft has been adopting implicitly CommonMark (based on 0.28) for all its documentation. So, in practice, CommonMark 0.28 is already an industry standard, and it should be promoted accordingly.


Alexandre Mutel noreply@talk.commonmark.org writes:

@jgm could we move forward and promote the current
0.28 version of CommonMark as 1.0.0.

I will think about this. The reason I have resisted
doing this is to make it easier to make breaking
changes on the way to solving the remaining problems.
(There are already some in HEAD.) I’m sorry about the
slow progress in the last two years, but stability
also has a good side, of course.

Microsoft has been adopting implicitly CommonMark
(based on 0.28) for all its documentation.

This is interesting news, which I hadn’t heard – what
is the source?


Afaik, there is no official source talking explicitly about them using CommonMark, but most (if not all) their new documentation at https://docs.microsoft.com/en-us/ should be relying on docfx/DFM (and maybe some internal non public templates for their website) and they have been actually migrating to markdig for their Markdown engine for the past year (and extending it with their own extensions/syntaxes for docfx), so they are now CommonMark compliant and they are also on babelmark3. They have a strong interest to have a high compatibility with GFM, as their DFM is just a superset of GFM, as most of their docs are also OSS on GitHub.


I would really love to see this happen. That would make me possible also to put a non 0.x.y version for markdig, as I have to wait that the specs are completed otherwise that would bring significant breaking changes.

Regarding the problems, from a practical perspective, I think that the current spec is perfectly fine and that’s what is most important. And as stated in the discussion in Beyond Markdown, if we really wanted to make this specs easier, this would require to fork/break entirely from the current Markdown that is commonly used elsewhere. CommonMark is the only standard available today, and if GitHub might not be the only user of CommonMark 0.28 now, it is such a significant big user/player that I would not expect the current CommonMark specs to change significantly.


Happy new year!
bumping this issue again related to promote the current spec version of CommonMark to 1.0.0
I don’t think that we are going to make any new substantial changes to the specs and it is important that we secure the current version that is already broadly used (at least from a few big players I’m aware of: GitHub, all new Microsoft documentation)
Could we make this happen? I would love to see 2019 as the year where CommonMark 1.0 is being done.


I echo the statement made above. I think it’s really important to release a 1.0.0 in the near future, especially since any necessary breaking changes can be implemented in a 2.0.0 version.


Where do you feel we are at on this today?


Re-bumping this. Large corporations have switched to CommonMark (GitHub, Microsoft…) and they are relying on the behavior of 0.29 specs, and as nothing much has changed since last year about the specs, could we make 0.29 the final 1.0?


I tend to agree with you @xoofx – but it’s up to @jgm. At the very least I have indicated how mature the project currently is on the homepage, and stopped promising any particular dates or versions.

Actual usage is its own kind of measurable success, for sure :bowing_man:

1 Like