Item — HN Reader

There are so many markup languages and conversion possibilities, just have a look on the to-from option from pandoc.

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

3 comments

There's a couple reasons why I think it would be bad if higher level headings would be considered more important. First, in HTML, <h1> is the top heading which directly maps to

= 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

Another argument in favor of adding markers for lower levels is that indenting the first character of a header typically indicates lower level headings in a table of contents.

    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.

From a technical implementation point of view, I agree. But I had the viewpoint of a visually guided human, the non-technical type.

That is also why I stick to reStructeredText, they circumnavigate ATX-style headers at all.

Concerning the baseline, doesn't the HTML5 standard just specify 6 ranks from <h1> … <h6>? Would be at least a candidate for common agreement on the lowest (highest) rank.

HTML5 also supports nestet <section> with their <h> tags. I’m not sure if there is a maximum nesting level in this case.

I think this is a bikeshedding criticism more than something that requires serious concern. Asciidoctor simply supports more out-of-the-box and officially than reStructuredText. Preferring reStructuredText to Asciidoctor this way is like comparing Python to Ruby for syntax alone. Function is just as important.

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.

Sounds like org-mode. All hail Emacsen.

Well worth the read. I agree.