Firstly, thanks so much for this project and community in general - the markdown ecosystem was (and in many spheres, still is) in dire need of this exact project.
Commonmark’s aim was to tie together disparate implementations to construct a single, flexible, relatively portable spec, covering most use cases. It has succeeded in this! However, in its goal to be most things to most people, there necessarily exists some vestigial duplication which makes the spec and new parsers more complicated and less approachable than they need to be. I do not suggest changing the spec to avoid this: rather, I wonder whether a parallel document (or annotations to the existing spec) which addresses degenerate features and recommends a “preferred” way of doing things (possibly with some reasoning) would be valuable to the community.
To borrow from the Zen of Python:
There should be one-- and preferably only one --obvious way to do it.
For example (and this is not the place for splitting hairs over exactly what the preferences would be), such a document may suggest preferring ATX headings over setext, because they are more flexible and less ambiguous. It may go on to recommend that trailing
# symbols are not used, and that the leading
# symbols are not indented. Unordered lists should prefer hyphens; ordered lists should prefer
<number><period> ; code blocks should prefer triple backticks; thematic breaks should use exactly three asterisks with no spaces; emphasis should use underscores, etc. Justifications can concern legibility, portability, discriminability from other language constructs, similarity to the HTML rendering, or any of the above. In some cases (like unordered lists), the decision can explicitly be arbitrary if there is no good justification one way or the other - but having a guideline is valuable in its own right (see spaces vs. tabs in python’s PEP8).
I suspect that the pressure Commonmark can exert on the markdown community at large may not be enough for these practices to instantly become convention, but it may be the only organisation which can authoritatively host such a document (whether or not attention is paid to it). It would present a smaller surface area for early-stage or lightweight parsers to target, further enhance portability for existing parsers where only a subset of Commonmark is supported, and be easier to learn and teach. And with best practices officially written down somewhere authoritative, everyone’s markdown could start looking more like everyone else’s markdown.
Such a document could be referred to as Minimal Markdown, or minimark.
I suspect that GitHub must have already made a lot of these sorts of decisions, because in converting their old sundown-compliant comments to commonmark-gfm, they must have had a way of resolving ambiguities from the AST.