Third level Setext-style headings with ~


As demonstrated in this plain text file, the option to have a third level for Setext-style headings might be useful, rather than being forced to switch to ATX-style headings or HTML for only part of the document. For example:

Main Heading

Section 1

Subsection 1.1

Subsection 1.2

Section 2

Subsection 2.1


AsciiDoc indeed uses tilde ~ for third-level underlined headings, but Commonmark cannot because this would conflict with fenced code blocks.

Texy and ReStructuredText support other characters: * and # or +, ^, _, :, ", ', `, <, >. Some of these are also reserved for other purposes in Markdown. The hyphen - is also for thematic breaks (or horizontal rules), and so are the underscore _ and the asterisk * which would thus probably be the best candidates for additional heading levels.

Anyhow, this has bad backwards compatibility for existing content and parsers.


I had forgotten about this, since ``` is the more common delimiter for fenced code blocks. I guess we can’t use this syntax then…

Regarding backward compatibility, the proposed syntax still looks natural in plain text, so without the extension it wouldn’t look too out of place at least. But it might be confusing to have some heading syntax in the core, and other heading syntax as an extension. CommonMark core has followed the philosophy of only including the features of the original Markdown spec, while also including new syntax for those features (e.g. fenced code blocks and significant list markers), so if another heading syntax was introduced it would be more consistent to add it to the core spec.