Harmonizing headings, horizontal rules, tables and even bullet lists

Extensions
1

Situation

  1. The underlines of ATX headings are restricted to = and -.
  2. Presentational horizontal rules or semantic section breaks can use -, * and _.
  3. Tables, in most flavors, use - and maybe = or ~ in the line separating headers and possibly footers from the body. The plus sign +, pipe |, space , colon : or, rarely, hash # may be used to mark column boundaries within such a line, depending on flavor.
  4. Bullet list items are introduced by any of -, + and *.
  5. We find the markup characters =, -, *, _, + and maybe ~ here.
    Some of them are used as affixes for inline markup as well: _/*, __/** and ___/*** (emphasis or italic / bold) in standard markdown and ~ (subscript vs. ^ for superscript) and ~~ or -- (deletion / strike-out) often along-side ++ (addition / insertion) in many flavors, also == (highlight / mark) in some.

As you can see, the hyphen-minus - is used in all four block markups, the equals sign = and the asterisk * each in two of them, the underscore _, tilde ~ and plus sign + each in one at most.
The hyphen-minus - is problematic to be used as inline markup, because traditionally, -- and --- can be converted to dashes, ‘–’ and ‘—’, possibly even if not surrounded by whitespace or punctuation; some prettifiers also convert a single hyphen-minus into a more appropriate character (e.g. a minus sign).

Three and more tildes ~~~ are already used for fences of special blocks (usually code listings today) and are equivalent to backticks there. Three dashes are also used to fence of YAML metadata blocks in some implementations, where the closing one can alternatively consist of dots ....

Goals

I believe if anyone wanted to extend any of the block formats, everyone should do so in a consistent, coordinated manner.

  • Heading underlines should be based on horizontal rules. In fact, I think you can safely think of horizontal rules as empty headings of a certain generic level.
  • Table headings should be based upon normal headings in turn.

Consequences

  • Extensions may support asterisk * and underscore _ ATX-like headings.

  • Extensions may support equals sign = horizontal rules or semantic breaks.

  • Extensions may support plus + for headings and rules.

  • As hierarchies go, = has to be top-level and - one below, because that’s been long established for headings. The order of the other ones can be selected more or less arbitrarily, but plus+ coming from lists, should probably be the lowest.

  • Syntactic extensions should never use any of =, _ and ~ as line prefixes unless it’s to introduce a list item, maybe a special one.

  • Multiple tildes should not be used for lines other than fences, i.e. neither in headings, rules nor tables.

  • Table markup should use lines of = to separate row groups (header, body, footer) and lines of - to separate rows if necessary (e.g. for cells spanning several rows).

What else?

2 Likes
2

Um, where I said “ATX”, I obviously meant “setext”. I can never remember which is which. Perhaps we should call them prefixed and underlined headings instead.