With the algorithm currently used by cmark and commonmark.js, there is no efficiency cost to allowing multiline setext headers. We store successive lines in paragraphs, and when we hit one that looks like a setext header line, we just convert the paragraph into a setext header. No backtracking is needed. Indeed, allowing multiline setext headers would eliminate the need for a check we currently do (to see if only one line of text has been parsed).
I’m leaning towards thinking multiline headers are the best interpretation here. People who hard-wrap their text to a fixed column width may occasionally need these (although stylistically it’s generally best to avoid overly long headers). Currently there’s no way to do multiline headers in CommonMark (or Markdown generally), so the change would increase expressive power.
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:
-
foo
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.
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 commonmark.org 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.
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).
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?
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.
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.
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.