Setext headers and empty list items

Spec
14

Hello all! I hope bumping this thread is the right thing to do, despite its age, since it’s the exact topic I wanted to bring up :bowing_man:

I recently opened an issue on Hedgedoc about this ‘empty, hyphenated list-item Vs. h2 setext’ issue. The maintainer also initially thought it was a problem on their side, but then realized it was conformant with commonmark, so opened an issue on Commonmark.

The argument for setext only requiring one - or = for single-character titles does make sense. However, the argument for setext requiring multiple - or = is that it would solve the list/header issue, and would be arguably closer to Gruber’s description:

Markdown offers two styles of headers: Setext and atx. Setext-style headers for <h1> and <h2> are created by “underlining” with equal signs (=) and hyphens (-), respectively.

(emphasis added)

This description, which arguably cites multiple - or =, appears to be backed up with the examples some lines later:

A First Level Header
====================

A Second Level Header
---------------------

In contrast, Commonmark example 83 states:

The underlining can be any length

With respective examples of h2 and h1:

Foo
-------------------------

Foo
=

Furthermore, as mentioned in the first post, the Commonmark 0.30 Specification, 4.3 Setext heading still states:

If a line containing a single - can be interpreted as an empty list items, it should be interpreted this way and not as a setext heading underline.

While it might be argued that…

Foo
-

should still be interpreted as an h2, I believe interpreting…

- Foo
    -

as an h2 is interpretation too far, and goes against the ‘readability’ maxim.

In conclusion, I:

  • generally support requiring multiple - or = for setext headers, and
  • strongly support indented, hyphenated list items not being interpreted as h2 setext header underlines for parent list items.
1 Like