Issues RESOLVED for 1.0 release

Spec
1

This is a companion topic for the CommonMark 1.0 release.

These are issues that were successfully resolved as we worked toward the 1.0 release.

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.

Disallow space between bracketed parts of reference link? (DONE)

See discussion here.

Should space be required after # in ATX headers? (MUST)

See discussion here.

(Leaving this as it already is - spaces are required.)

Remove hard-coded list of protocols for autolinks? (DONE)

Discussion here.

Inconsistent handling of spaces in links? (DONE)

Should we disallow spaces in <> links?

Matthijs_Kooijm notes:

Spaces in links seem to be handled inconsistently. Example 399 says “Spaces are not allowed in autolinks”. However, Example 331 says, about regular link destinations, “If the destination contains spaces, it must be enclosed in pointy braces”.

This seems a bit confusing to me, that sometimes I can use <> to explicitly allow spaces in urls, but in autolinks it is explicitly forbidden. I guess the rationale is probably to prevent false-positives for autolinks, whereas that risk is far smaller for regular link destinations, which makes sense.

This should probably be resolved consistently, one way or the other.

URL normalization (DONE)

The spec just needs some words to the effect that renderers may do some normalization, and this isn’t mandated.

Allow setext headers to interrupt paragraphs for consistency (DONE)

EDIT: Resolved in favor of allowing multiline setext headings.

Our spec does not allow setext headers to interrupt a paragraph. So the example

Paragraph
Header
=====
Paragraph

does not get parsed as containing a header. I’m not sure there’s any very strong rationale for not allowing setext headers to interrupt a paragraph, so maybe this should be revisited.

Interesting comparison of different implementations here: Babelmark 2 - Compare markdown implementations

Note that Markdown.pl did not allow lists to interrupt paragraphs, but did allow (both setext and atx) headers and block quotes to.

Possible spec/test case change:

--- a/test/spec.txt
+++ b/test/spec.txt
@@ -904,23 +904,20 @@ line] in a list item or block quote:
 <hr />
 .

-A setext header cannot interrupt a paragraph:
+A setext header can interrupt a paragraph:

 .
 Foo
 Bar
 ---
-
 Foo
 Bar
 ===
 .
-<p>Foo
-Bar</p>
-<hr />
-<p>Foo
-Bar
-===</p>
+<p>Foo</p>
+<h2>Bar</h2>
+<p>Foo</p>
+<h1>Bar</h1>
 .

Another possibility (mentioned here) would be to allow setext headers to have multiple lines, so that

Header line one
and line two
-------------------

gets parsed as a single setext header. Requests for multiline headers are not uncommon, so that is a point in favor.

Remove two-blanks rule? (DONE)

EDIT: removed.

The two-blanks rule violates the Principle of Uniformity (that putting something in a list item doesn’t affect its meaning).

Get rid of it?

See discussion here.

Setext header and list precedence issue (DONE)

See discussion here concerning examples like

1. hi
-----

I don’t see a good way to modify our parsing strategy to allow the “numbered header” interpretation, so I think we’re stuck with the “list before rule” interpretation here. You’ll need to escape the period if you want to avoid the list interpretation.

1 Like