[Arnavion]

The one thing that puts me off the most is the limit of two levels of headings.

(There are three, but you need one for the page title, and it would be awkward to reuse the "title" heading level for "section" headings. Even if you got over this awkwardness, three levels is still annoyingly constraining.)

[dancek]

IMHO you could just use

    # Page title
    
    # 1. First heading

and go from there. The format is meant to be human-understandable, not machine-readable.

But your point is a good one, and made me wonder how the documentation of Gemini itself handles the issue. And behold, the Gemini FAQ [0] itself has the first level 1 heading as

    ## 1. Overview

and the second one as

    # 2. Protocol design

That's really disturbing once you notice, but I'd wager that hundreds of people have read the page and not noticed.

[0]: https://proxy.vulpes.one/gemini/gemini.circumlunar.space/doc...

[Arnavion]

>IMHO you could just use [...] and go from there. The format is meant to be human-understandable, not machine-readable.

I disagree that it's not meant to be machine-readable. Accessibility clients rely on heading levels to infer sections and subsections. HTML has `<section>`, but a Gemini client only has heading levels to go by.

But anyway, that's why I said it'd be "awkward", not "impossible", to reuse the title heading level for section headings. The rich-text Gemini client as well as the human user reading the raw file have to special-case that the first `#` is the page title and not equivalent to other `#` in the file.

And like I said, even once you get over that awkwardness, three levels is still very limiting. I'm looking at a markdown documentation file right now that has five levels of headings. That's with one unique level for the page title, so even if it were to reuse the title heading level for the section headings it would still require four levels of headings.

>And behold, the Gemini FAQ [0] itself has [...]

Ha, I didn't know about that one. I had noticed in the past that the homepage [1] uses a unique level for the title, but the specs page [2] does not because it can't afford to.

[1]: https://portal.mozz.us/gemini/gemini.circumlunar.space/?raw=...

[2]: https://portal.mozz.us/gemini/gemini.circumlunar.space/docs/...

[Semiapies]

I also noticed a few cases of trying to use markdown emphasis on the docs. If you can't even write the platform docs without having to work around your markup system, maybe don't go on about how the spec will never need updating.

[tjalfi]

I would argue that being limited to two levels is a feature.

Here's a related quote[0] from Edward Tufte.

"Dr Spock's Baby Care is a best-selling owner's manual for the most complicated 'product' imaginable -- and it only has two levels of headings. You people have 8 levels of hierarchy and I haven't even stopped counting yet. No wonder you think it's complicated."

[0] http://web.archive.org/web/20080610092329/http://blogs.sun.c...

[spwhitton]

Yes, this really bothers me too. Title, sections, subsections and subsubsections is not too much sectioning.