# Third level Setext-style headings with ~

**URL:** <https://talk.commonmark.org/t/third-level-setext-style-headings-with/2664>\
**Category:** Extensions\
**Created:** [December 1, 2017, 4:35am UTC](https://talk.commonmark.org/t/third-level-setext-style-headings-with/2664 "2017-12-01T04:35:48Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\
**Post date:** [December 1, 2017, 4:35am UTC](https://talk.commonmark.org/t/third-level-setext-style-headings-with/2664/1 "2017-12-01T04:35:48Z")

</div>

As demonstrated in [this plain text file](https://github.com/git/git/blob/master/Documentation/technical/hash-function-transition.txt), 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:

```auto
Main Heading
============

Section 1
---------

Subsection 1.1
~~~~~~~~~~~~~~

Subsection 1.2
~~~~~~~~~~~~~~

Section 2
---------

Subsection 2.1
~~~~~~~~~~~~~~

```

---

<div class="post-metadata">

**Author:** ![Crissov](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/crissov/32/1455_2.png) [@Crissov](https://talk.commonmark.org/u/Crissov)\
**Post date:** [December 1, 2017, 10:42pm UTC](https://talk.commonmark.org/t/third-level-setext-style-headings-with/2664/2 "2017-12-01T22:42:09Z")

</div>

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

> **[Lightweight markup language | Underlined headings](https://en.wikipedia.org/wiki/Lightweight_markup_language#Underlined_headings)**
>
> The first style uses underlines, i.e. repeated characters (e.g. equals =, hyphen - or tilde ~, usually at least two or four times) in the line below the heading text.

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.

---

<div class="post-metadata">

**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\
**Post date:** [December 2, 2017, 4:43am UTC](https://talk.commonmark.org/t/third-level-setext-style-headings-with/2664/3 "2017-12-02T04:43:17Z")

</div>

> [@Crissov](#):
>
> AsciiDoc indeed uses tilde ~ for third-level underlined headings, but Commonmark cannot because this would conflict with fenced code blocks.

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.