Issues we MUST resolve before 1.0 release [6 remaining]

I’m wondering how can we help to go to 1.0 release? What would help you @jgm concretely?


I have added some items to the list, I’m afraid.


What and where is the current list?

Regarding the odd list case with the link reference definition, the source is probably at Example 0.28:

Link reference definitions can occur inside block containers, like lists and block quotations.

Example 175 shows how a paragraph can start directly after a line containing a reference link definition.

A sub-question is whether this should be an empty list item:


There is no example or prose explaining exactly that.

I have found myself wishing such embedded link reference definitions would work but would still be shown in the output, especially in lists where they otherwise always lead to empty list items because nothing can precede or follow them therein.

- [foo]: bar
<li><a href="bar">[foo]: bar</a></li>

It’s been 2½ years since this list was started, at least 3½ years since this forum was opened, over 5 years since Jeff’s The Future of Markdown.

It’s now been a year since GitHub adopted CommonMark.

Releasing 1.0 will further the goals and adoption of CommonMark. It will also allow the development of CommonMark v1.1 or v2 to move forward, which will further the goals and adoption even more.

So @jgm @codinghorror, what needs to happen to resolve this list? What can the community do?

Perhaps add a V1 milestone to the issues database, add the issues corresponding to the above to the milestone, and start taking pull requests? BTW, maybe announce that this forum is for design/new feature discussion, but bugs in the spec should get moved into GitHub, with a message on such threads here with a link to the GitHub issue. It will make this all easier to manage.


I think part of the reason for the delay in releasing a “1.0” version of the core spec is that it would be very hard to patch without breaking backward compatibility, and a 1.0 version isn’t strictly needed for the spec to be useful in production. I don’t disagree with your points though @vas.

That said, I see no reason why work couldn’t commence on extension specs before the core spec reaches 1.0 (by other members of the community if @jgm is busy). Formalising some of the extensions from GitHub Flavored Markdown - tables, task list items, strikethrough, autolinks, and disallowed raw HTML - here on would be good place to start. Alternatively, if CommonMark extensions as part of the CommonMark project are no longer on the cards, that’s something the community would benefit from being made aware of so that extension specs could be developed independently.

1 Like

If what you say is true, it has been true for 2½ years, and implies such wide adoption that breaking backward compatibility keeps the spec stuck this way for 2½ years, which in turn means we have a de facto 1.0 release. If so, we should make it official and move on to v1.1 where we’d have the freedom to fix things with minor backward incompatibility.

If what you say is not true, we can address this list for v1.0 and do it soon.

A standard that can’t take a stand is just a recommendation.


Some of the issues listed here aren’t so minor. For the issues with linked forum topics, these are known issues that are still under discussion; the implementation hasn’t yet been decided. If you want to see a 1.0 release sooner, contributing to those individual discussions would help move the spec towards 1.0 as they have been explicitly stated as 1.0 blockers (independent of time).

1 Like

Seniority certainly has to be taken into account at some point.
But let’s see. Github does not it any more. it uses commonmark.

How to count now ? it remains 13,537,268 - 1 users of kramdom ? Overstated?
May be should we also precise github use a github flavored commonmarkdown spec instead of a github flavored markdown (gfm).
Is it that an unconditional endorsement for commonmark diffusion around a well approved status quo ?

As others, i appreciate and thanks the efforts of the community around this project.
But IMHO, it seems there is some bikeshedding around important issues like:

  • css class
  • metadata
  • extensibility
  • ast

Issues way more important than to handle uncountable variants of line break.

As any project, open source should know how to stay on track and on time…

I agree, and that’s essentially what I’ve been saying in a different, but less presumptive, way.

But saying things like “It seems that commonmark is slowly dying” is neither accurate nor helpful. It’s no more accurate than saying “It seems that Gruber’s Markdown is slowly dying.” We all know the opposite is true. The problem isn’t death/lack of adoption, it’s fragmentation.

Neither are your statistics helpful, because you know that saying about lies and statistics. Such comments aren’t going to spur things to move. It’s not how leaders talk, nor is it how you get leaders to listen.

How about you start a new forum topic making your above bikeshedding case, with a solid line of reasoning, sans hyperbole?

1 Like

GitHub Pages used to use kramdown, but now it follows CommonMark.

FYI: GitHub Pages still uses kramdown. GitHub uses CommonMark (with GitHub Flavored Markdown extensions) for READMEs and markdown rendered on GitHub itself (but not for GitHub Pages). Sorry if this sounds confusing.

You’re right. I was misremembering the time they switched to kramdown.

From @notriddle’s link:

GitHub-flavored Markdown is supported by kramdown by default, so you can use Markdown with GitHub Pages the same way you use Markdown on GitHub.

In other words you can use CommonMark with GitHub Pages the same way you use it on GitHub.

And yes, even kramdown supports CommonMark. Does that mean we get to add kramdown’s numbers to CommonMark’s?

That’s a rhetorical question, so please don’t answer. This debate is starting to get silly, and sounding like national politics. Let’s get back to progress with CommonMark, whether that’s nailing 1.0 first or declaring it done, we need to move on to 1.1 asap. We need to move to head off even more fragmentation.

JFTR, Kramdown’s GFM mode for Jekyll (which is what GitHub Pages is build upon) does not conform to Commonmark and probably never will. If I’m not confusing things again, GitHub uses commonmarker for .md file previews but cmark-gfm for READMEs.

@jgm are this list and the related should list up to date? I’d like to know before I spend any time on it.

Preservation of spaces in backtick code I believe was resolved in the v0.29 spec update.

Reconsider allowing lists to break paragraphs appears to have been decided, but not really?

I’ve updated this a bit. Several items crossed off.
However, I don’t think the list is complete. See the commonmark/commonmark-spec issue tracker. Not all of the issues there are “1.0” issues, but at least some of them are (see especially the ones marked with the 0.30 milestone.)


@jgm @codinghorror would it make more sense to maintain this list in one and only one place, i.e. GitHub? Maybe create 1.0 minimum and 1.0 should milestones (or labels). Issues can always be moved to earlier milestones as desired.

And then replace the top of this topic with a link to those lists on GitHub.


@jgm @codinghorror would it make more sense to
maintain this list in one and only one place, i.e.
GitHub? Maybe create 1.0 minimum and 1.0 should
milestones (or labels). Issues can always be moved
to earlier milestones as desired.

That would make a lot of sense, I agree.

1 Like

This looks long-settled, but I would like to briefly dispute the “tension from the fix is minor” bit: since github switched to commonmark, I’ve been running into broken headers of this sort all the time. One only need look at the number of pingbacks a relevant issue accumulated over the course of a year, before getting locked for being too spammy. (For hashtags in particular, special-casing h1 might be warranted?)

In light of the last edit on April 10, shouldn’t the number in the title be reduced to 6?