@jgm jgm released this Aug 2, 2017 · 30 commits to master since this release

Assets 2
  • Allow unlimited balanced pairs of parentheses in link URLs
    (@kivikakk, commonmark/cmark#166). The rationale is that there are many URLs
    containing unescaped nested parentheses. Note that
    implementations are allowed to impose limits on parentheses
    nesting for performance reasons, but at least three levels
    of nesting should be supported.

  • Change Rule 14 for Emphasis. Previously the nesting
    Strong (Emph (...)) was preferred over Emph (Strong (...)).
    This change makes Emph (Strong (...)) preferred.
    Note that the commonmark reference implementations
    were not entirely consistent about this rule, giving
    different results for




    This change simplifies parsing. It goes against the majority
    of implementations, but only on something utterly trivial.

  • Clarify definition of delimiter runs (Aidan Woods, #485).

  • Clarify precedence of thematic breaks over list items
    in the list spec, not just the thematic break spec (Aidan Woods).

  • Clarify definition of link labels and normalization
    procedure (Matthias Geier, #479).

  • Clarify that the end of an HTML block is determined by its
    start, and is not changed by HTML tags encountered inside
    the block. Give an example of a case where a block ends
    before an interior element has been closed (Yuki Izumi, #459).
    In the future we might consider changing the spec to handle
    this case more intuitively; this change just documents more
    explicitly what the spec requires.

  • Acknowledge Aaron Swartz's role in developing Markdown.

  • Remove misleading backslash in example for disabling image markup
    (Matthias Geier).

  • Fix Unicode terminology (general category, not class)
    (Philipp Matthias Schaefer).

  • Add another illustrative case for code spans (#463).

  • Remove possibly misleading 'either's (#467).

  • Fix typo (Aidan Woods).

  • Clarify that some blocks can contain code spans (Matthias Geier).

  • Fix typo and clarified tab expansion rule (Scott Abbey).

  • Add a missing "iff" (Matthias Geier).

  • Add release checklist.

  • Added npm package for spec (Vitaly Puzrin).

  • Remove SPEC variable from Makefile.

Nov 18, 2016


Bump verison to 0.27.

@jgm jgm released this Jul 15, 2016 · 97 commits to master since this release

Assets 2
  • Empty list items can no longer interrupt a paragraph.
    This removes an ambiguity between setext headers and
    lists in cases like


    Removed the "two blank lines breaks out of lists" rule.
    This is incompatible with the principle of uniformity
    (and indeed with the spec for list items, which requires
    that the meaning of a chunk of lines not change when it
    is put into a list item.)

  • Ordered list markers that interrupt a paragraph must start with 1.

  • Improved the section on tabs. Added some test cases for ATX
    headers and thematic breaks. Clarified that it's not just cases
    that affect indentation that matter, but all cases where whitespace
    matters for block structure.

  • Removed example of ATX header with tab after #.

  • Allow HTML blocks to end on the last line of their container
    (Colin O'Dell, #103).

  • Spec changes in strong/emph parsing. See
    for motivation. This restores intuitive parsings for a number of cases.
    The main change is to disallow strong or emph when one of
    the delimiters is "internal" and the sum of the lengths of
    the enclosing delimiter runs is a multiple of 3. Thus,
    **foo*bar*** gets parsed <strong>foo*bar</strong> rather than
    <em><em>foo</em>bar</em>** as before. Thanks to Fletcher Penney
    for discussion.

  • Add tests to check that markdown parsing is working fine after an HTML
    block end tag (Alexandre Mutel).

  • Add test case for nested lists with an indent > 4 (Alexandre Mutel).

  • Cleaned up terminology around lazy continuation lines. Added some links.

  • Fixed broken links and typos (Artyom, Matthias Geier, Sam Estep).

  • Use instead of < in list item spec for clarity.

  • Add point about readibility to "What is Markdown" section.

  • Add example for list item starting with a blank line with spaces
    (Robin Stocker).

  • Make interact more button-like and clearer (Jeff Atwood).

  • spec_tests.py: exit code is now sum of failures and errors.

  • spec_tests.py: specify newline when opening file.

@jgm jgm released this Jul 15, 2016 · 134 commits to master since this release

Assets 2
  • Added several more tab-handling cases (see commonmark/cmark#101).
  • Fixed spec test for tabs. In the blockquote with a tab following
    the >, only one space should be consumed, yielding two spaces
    at the beginning of the content.
  • Update license year range to 2016 (Prayag Verma).
  • Fixed typo: setext heading line -> setext heading underline (#389).
  • Fixed date 2015->2016 (#388)

@jgm jgm released this Jan 13, 2016 · 147 commits to master since this release

Assets 2


  • New format for spec tests, new lua formatter for specs.
    The format for the spec examples has changed from



    ```````````````````````````````` example

    One advantage of this is that spec.txt becomes a valid
    CommonMark file.

  • Change tests/spec_test.py to use the new format.

  • Replace tools/makespec.py with a lua script, tools/make_spec.lua,
    which uses the lcmark rock (and indirectly libcmark). It can
    generate HTML, LaTeX, and CommonMark versions of the spec. Pandoc
    is no longer needed for the latex/PDF version. And, since the new
    program uses the cmark API and operates directly on the parse tree,
    we get much more reliable translations than we got with the old
    Python script (#387).

  • Remove whitelist of valid schemes. Now a scheme is any sequence
    of 2-32 characters, beginning with an ASCII letter, and containing
    only ASCII letters, digits, and the symbols -, +, ..
    Discussion at http://talk.commonmark.org/t/555.

  • Added an example: URI schemes must be more than one character.

  • Disallow spaces in link destinations, even inside pointy braces.
    Discussion at http://talk.commonmark.org/t/779 and

  • Modify setext heading spec to allow multiline headings.
    Text like


    is now interpreted as heading + paragraph, rather than
    paragraph + thematic break + paragraph.

  • Call U+FFFD the REPLACEMENT CHARACTER, not the "unknown code
    point character."

  • Change misleading undefined entity name example.

  • Remove misleading claim about entity references in raw HTML
    (a regression in 0.23). Entity references are not treated
    as literal text in raw HTML; they are just passed through.

  • CommonMark.dtd: allow item in custom_block.

@jgm jgm released this Dec 29, 2015 · 160 commits to master since this release

Assets 2


  • Don't allow space between link text and link label in a
    reference link. This fixes the problem of inadvertent capture:

    [foo] [bar]
    [foo]: /u1
    [bar]: /u2
  • Rename "horizontal rule" -> "thematic break". This matches the HTML5
    meaning for the hr element, and recognizes that the element may be
    rendered in various ways (not always as a horizontal rule).
    See http://talk.commonmark.org/t/horizontal-rule-or-thematic-break/912/3

  • Rename "header" -> "heading". This avoids a confusion that might arise
    now that HTML5 has a "header" element, distinct from the "headings"
    h1, h2, ... Our headings correspond to HTML5 headings, not HTML5 headers.
    The terminology of 'headings' is more natural, too.

  • ATX headers: clarify that a space (or EOL) is needed; other whitespace
    won't do (#373). Added a test case.

  • Rewrote "Entities" section with more correct terminology (#375).
    Entity references and numeric character references.

  • Clarified that spec does not dictate URL encoding/normalization policy.

  • New test case: list item code block with empty line (Craig M.

  • Added example with escaped backslash at end of link label (#325).

  • Shortened an example so it doesn't wrap (#371).

  • Fixed duplicate id "attribute".

  • Fix four link targets (Lucas Werkmeister).

  • Fix typo for link to "attributes" (Robin Stocker).

  • Fix "delimiter" spellings and links (Sam Rawlins).

  • Consistent usage of "we" instead of "I" (renzo).

  • CommonMark.dtd - Rename html -> html_block,
    inline_html -> html_inline for consistency. (Otherwise it is too
    hard to remember whether html is block or inline, a source of
    some bugs.)

  • CommonMark.dtd - added xmlns attribute to document.

  • CommonMark.dtd - added custom_block, custom_inline.

  • CommonMark.dtd - renamed hrule to thematic_break.

  • Fixed some HTML inline tests, which were actually HTML blocks, given
    the changes to block parsing rules since these examples were written

  • Normalize URLs when comparing test output. This way we don't fail
    tests for legitimate variations in URL escaping/normalization policies

  • normalize.py: don't use HTMLParseError, which has been removed
    as of python 3.5 (#380).

  • Minor spacing adjustments in test output, to match cmark's output,
    since we test cmark without normalization.

  • makespec.py: remove need for link anchors to be on one line.

  • makespec.py: Only do two levels in the TOC.

  • Use display:inline-block rather than floats for side-by-side.
    This works when printed too.

  • Added better print CSS.

Aug 24, 2015


Bump spec version to 0.22.
Jul 15, 2015
Added date on spec.

@jgm jgm released this Jul 15, 2015 · 231 commits to master since this release

Assets 2
  • Changed handling of tabs. Instead of having a preprocessing step
    where tabs are converted to spaces, we now handle tabs directly in
    the parser. This allows tabs to be retained in code blocks and code
    spans. This change adds some general language to the effect that,
    for purposes of determining block structure, tabs are to be treated
    just like equivalent spaces.
  • Completely rewrote spec for HTML blocks. The new spec provides
    better handling of tags like <del>, which can be either block
    or inline level content, better handling of custom tags, and
    better handling of verbatim contexts like <pre>, comments,
    and <script>.
  • Added 9-digit limit on ordered list start number.
    Some browsers use signed 32-bit integers for indexing
    the items of an ordered list, and this can lead to odd
    or undefined behavior if 10-digit start numbers are allowed.
  • Allow (non-initial) hyphens in tag names (#239). Custom
    tags in HTML5 must contain hyphens.
  • Clarified that HTML block is closed at end of containing
    block, not just end of the document (as with fenced code blocks.)
  • Specify nested link definition behavior in prose (Benjamin
    Dumke-von der Ehe).
  • Added test for edge case in link reference parsing
    (Benjamin Dumke-von der Ehe, see commonmark/commonmark.js#49).
  • Added link tests with fragment identifiers and queries (David
    Green, #342).
  • Added test cases with a literal backslash in a link destination
    (see commonmark/commonmark.js#45).
  • Added test for entity &ngE; which resolves to two code points.
    Put entity tests on several lines for readability (see
  • Fixed broken "pre" literal HTML example. Contents
    weren't escaped properly.
  • Simplified defn of "unicode whitespace character,"
    rectifying omission of line tabulation, U+000B (#343).
  • Removed ambiguity in definition of "line" (#346).
  • Rewrapped two prose lines so + does not begin a line (#347).
  • Added another test with overlapping emphasis markers.
  • Fixed link to 'attributes'.
  • Revised appendix, "A parsing strategy," and
    added a description of emphasis/link parsing algorithm.
  • spec_tests.py - set options for conversions, set library
    paths in a more cross-platform way.
  • spec_tests.py: force utf-8 on test failure output and
    --dump-tests (#344, #345).
  • spec_tests.py: Properly handle visible tab in expected output.
  • normalize.py: Don't collapse whitespace inside pre tag.
  • Added spec.html to .gitignore (#339).
  • Add -dev suffix to spec version after release (eksperimental).
  • Rename "non-space" to "non-whitespace" (Konstantin Zudov, #337).

@jgm jgm released this Jun 8, 2015 · 267 commits to master since this release

Assets 2
  • Require at least one nonspace character in a link label (#322).
  • Require replacement (rather than omission) of U+0000 (#327).
  • Clarified that entities resolving to U+0000 are to be
    replaced by U+FFFD (#323).
  • Removed statement that what counts as a line ending is
    platform-dependent (#326). We now count \r, \n,
    or \r\n as a line ending regardless of the platform.
    (The line ending styles can even be mixed in a single document.)
  • Defined "space."
  • Revised "non-space character". Previously a non-space character
    was defined as anything but a space (U+0020). Now it is anything
    that is not a whitespace character (as defined in the spec).
  • Clarified that tab expansion is a preprocessing step (#330).
  • Clarified lazy block quote examples (#328).
  • Clarified precedence of indentation that meets conditions for
    both list item continuation blocks and indented code.
  • Added a test case with # directly followed by a letter
    (not an ATX header).
  • Added two test cases illustrating that a list at the
    outer level can have items that are indented by more
    than four spaces (see commonmark.js#42 and
  • Fixed typo in emphasis examples.