Setext headings

Spec
1

Hi :slight_smile:

I want to write in Markdown so that readers can easily read my documents, whether or not they have a Markdown interpreter. As I understand it, Markdown was designed for this purpose.

For this purpose, I don’t like ATX headings at all, as they are difficult to read in plain text. ATX headings level 6 are much more visible than ATX headings level 1.
However, there are Setext headings I can use instead.

The problem with Setext headings is that they only go up to level 2!

What do you think about this, please? :slight_smile:

Setext heading level 1
======================

Setext heading level 2
++++++++++++++++++++++

Setext heading level 3
----------------------

Setext heading level 4
= = = = = = = = = = =

Setext heading level 5
+ + + + + + + + + + +

Setext heading level 6
- - - - - - - - - - -
1 Like
2

I like the way reStructuredText does headings: you can use whatever style you want, and the order in which they’re encountered determines how they’re mapped to a hierarchy.

3

I thought this had been discussed thoroughly in the past already, but I’ve only found threads that consider one detail or another, e.g. flower boxes and fully boxed headings.

Equals sign = and hyphen-minus - underlines must remain top and second level, respectively, for compatibility with existing content and parsers.

Tilde ~ underlines cannot work because they are used for code block fences, likewise grave accent `.

It might be possible to reuse the hash mark #, but its role in ATX heading prefixes (and optional suffixes) makes it prone to bugs and misunderstandings.

Variant 1

Reusing the other two allowable characters from thematic breaks, which are also visually horizontal lines in code (and possibly presentation), seems like a sensible approach. They are asterisk * and underscore _. Since they are also the affix characters used to delimit inline emphasis, there is a certain possibility of mistreatment in legacy implementations. As asterisk is a tad stronger than underscore in flanking behavior, I’d see it as the higher level. This also agrees with other lightweight markup languages, where * is boldface / strong emphasis and _ is italic / normal emphasis. The counter argument would be that the underscore at least is a horizontal line like the existing ones.

Other ASCII punctuation that would be available and looks acceptable, are the plus sign + and the circumflex ^. The former is already used as a line marker for bullet list items alongside - and *, the latter is only used by extensions yet (e.g. for superscripts).

H1
===

H2
---

H3
***

H4
___

H5
+++

H6
^^^

Variant 2

The underscore looks particularly misplaced, in my opinion. Every punctuation mark that’s graphically located (mostly) on the base line will, e.g. period . or comma ,. The only other ones located at the top of the glyph box, are the replacement quotation marks " and apostrophe '. If authors use enough of those in a sequence, it actually looks like an underline.

H1
===

H2
---

H3
^^^

H4
"""

H5
'''

H6
***

(I’m more open to an alternative order of levels in this variant.)

4

I don’t think it makes sense for most documents to use more than three levels of heading. If I was going to suggest a third setext header, it would use apostrophe, since it is physically closer to the previous line, so the resulting header will be vertically smaller than h2:

Level 1
=======

Level 2
-------

Level 3
'''''''

The trouble with using more are:

  • In markdown, you have to do it by hand, so a single logical operation where you move a sub-subsection into a subsection requires you to schlep around with turning its sub-sub-subsections into sub-subsections.
  • A heading is not a caption. If your sub-sub-subheader is intended to label only one paragraph, then it’s too bad, because semantically it labels every paragraph after it until it reaches a header of equal or higher level.

If your document is truly complex enough to warrant more than two or three levels of heading, then it might be complex enough to warrant tooling that can do fenced sections instead of simple headers.

1 Like
5

Totally agree![1][2][3]

There are some exceptional cases, e.g. legal documents and some technical documents like specifications. In both those cases they use hierarchical numbering to make so much nesting manageable. We have ATX headings for those cases. If we really needed to make Setext work for those cases, I’d suggest letting the numbering rather than the underline style determine level:

1. H1
-----

1.1 H2
------

1.1.1 H3
--------

1.1.1.1 H4
----------

  1. [ Why don’t Tufte classes have subsubsections? ↩︎

  2. It is also notable that the Feynman lectures (3 volumes) write about all of physics in 1800 pages, using only 2 levels of hierarchical headings: chapters and A-level heads in the text. It also uses the methodology of sentences which then cumulate sequentially into paragraphs , rather than the grunts of bullet points. Undergraduate Caltech physics is very complicated material, but it didn’t require an elaborate hierarchy to organize. A useful decision rule in thinking and showing is “What would Feynman do?” - from Book design: advice and examples | Edward Tufte ↩︎

  3. How many heading levels are there in your document? - Reinout van Rees ↩︎