= heading
If you were to do it the other way around, there's no easy way to know which would would map to h1
======= this?
============= this?
The second reason why is because you have to have a baseline of maximum-importance. It's like ticket priorities capping out at P0 for maximum priority. The first intuitive thought would be that P5 should be more important than P0, but if you don't set a baseline of maximum importance, then there will always be someone who feels their thing is slightly more important.
========== Top level heading
=========== Super top level heading
============== Extra super top level heading deluxe
Chapter 1 ............... 5
Section 1a ............. 7
Section 1b ............ 11
Chapter 2 .............. 17
Section 2a ............ 21
is nicely similar to # Chapter 1
Lorem ipsum dolor sit amet.
## Section 1a
Lorem ipsum dolor sit amet.
## Section 1b
Lorem ipsum dolor sit amet.
# Chapter 2
Lorem ipsum dolor sit amet.
## Section 2a
Lorem ipsum dolor sit amet.That is also why I stick to reStructeredText, they circumnavigate ATX-style headers at all.
In Asciidoctor, I can:
* Use GraphViz (and other diagram) docs to describe architectural components.
* Actually test my example code, using named, delineating comments in my test suite and including the code between those comments as an example in my file.
* Support for WARNING, NOTE, etc. callout "admonitions"
* Auto-numbered list blocks with "."
Some of these may be possible with reStructuredText, and can definitely be supported with third party plugins, but all of this is first-party and amazing.
Note: IntelliJ's Asciidoctor plugin is incredible and it live renders mathematical equations AND graphing support in addition to everything else.
Personally, I prefer reStructuredText, its design feels more consistent in comparison to the ambiguous implementations of the various markdown dialects.
In Asciidoc, I do not like that lower lever headings occupy more markers than higher level ones. Visually,
=== This heading
appears more important than
== This heading
By the way, a good comparison is at http://hyperpolyglot.org/lightweight-markup