Here are some issues in the spec that must be resolved before a 1.0 release.
To keep us focused, the optional should resolve issues are in this topic and successfully resolved issues are in this topic.
To keep things organized, please comment in the linked discussions or issues, not here. If there’s no linked discussion, start a new one on this forum. I will edit this as things are resolved or new issues come up.
Code blocks and spans
Backtick fences and inline code collision
There’s an ambiguity between backtick fenced blocks and backtick inline code that needs to be resolved explicitly.
Currently this doesn’t get parsed as a code span:
``` zounds ## `##`` kebobble `` ```
Discussion here and an issue here and related issue here.
Links within links
Currently we disallow them and favor the innermost link.
Should we allow links within links?
Quotes in titles
Michel Fortin notes, regarding nested quotes in titles:
There sure is room for more consistency with various quote styles and disallowing non-sensial combinations of
). But take note:
stmd is the only implementation not supporting unescaped quotes. Babelmark 2 - Compare markdown implementations.
neither Markdown.pl, PHP Markdown, nor many other parsers let you escape a double quote (or a single quote), so the obvious solution is unfortunately non-portable and you’ll have to recommend using
It seems to me that the backslash-escapes should work in these contexts. There’s no clear reason why they should be disallowed; they are clearly useful; and the syntax description never says that they don’t work in these contexts. Allowing them to work removes 50% of the motivation for allowing nested quotes. Allowing you to use other quote types for titles across the board (’ or ()) removes another 25%. Or so I reasoned, anyway. There is a backwards-compatibility concern, which is serious, though I’ll bet the cases affected are very rare.
See Delimiters in link and image title attributes · Issue #308 · commonmark/commonmark-spec · GitHub
Odd reference link/list case
- [foo]: bar baz
produces a list with one item,
baz. Is this really right? (This seems like an implementation issue rather than a spec problem.)
(This issue still exists as of April 2019; an issue should be created in commonmark/commonmark, as I think this is an implementation bug, and the case should be added as an example to the spec.)
Reconsider allowing lists to break paragraphs
There’s a big discussion here:
The resolution we achieved still feels like a hack, and not really principled. Is there a better way?
Handling of tabs needs to be further specified in the spec. See
The change in tab handling (preserving tabs but trying to treat them as if they were converted to spaces at a tab stop of 4 when processing block structure) has some residual issues, and we need to go through the whole spec again with this in mind. We also need lots more test cases involving tabs.
See this issue for some good cases.
E.g. what does the spec say to do for
This is a bit unclear. Presumably we should have a code block, but what should be in it?
We should add test cases to the spec with tabs after list markers, block quote markers, and elsewhere.