Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

H4-H6 should be handled per Gemini spec #1

Closed
mntn-xyz opened this issue Aug 8, 2021 · 3 comments
Closed

H4-H6 should be handled per Gemini spec #1

mntn-xyz opened this issue Aug 8, 2021 · 3 comments
Labels
bug Something isn't working
Milestone

Comments

@mntn-xyz
Copy link
Contributor

mntn-xyz commented Aug 8, 2021

First of all, thanks for making this! I plan on using it in a project.

The Gemini spec only supports three levels of headings: "Headings are limited to a single line and start with either one, two or three # symbols followed by one mandatory space character"

The extra #s generated by gmnhg seem to be inconsistently handled by some clients I've tried. It seems that the generated headings should be limited to three levels, although it would be nice to include some additional markup to help people distinguish H3 from H4-H6. It could be as simple as this:

### # Heading 4
### ## Heading 5
### ### Heading 6

Or maybe another character would be better?

### + Heading 4
### ++ Heading 5
### +++ Heading 6
@tdemin
Copy link
Owner

tdemin commented Aug 8, 2021

@mntn-xyz very true. I just tested this with Amfora, and it handles whichever is the number of shebangs there is in the Gemtext document as though it was a heading of the third level:

Amfora test with multiple shebangs

There seems to be no good graceful "lossless" way of doing that, as we could do either of these:

  1. what you suggested: pad headings with extra characters (which breaks nothing but probably doesn't look right to people who are already tied to Markdown's six levels, which funnily enough includes me)
  2. truncate the rest of the H4-H6 headings (which would essentially turn all Markdown's H4-H6 headings to Gemini's H3)
  3. bail out on encountering H4-H6 completely and treat these as an input error which probably isn't what you call "graceful" and prevents you from using H4-H6 in your original Hugo site.

For now 1 appears to be the solution that breaks (almost) nothing?

@mntn-xyz
Copy link
Contributor Author

mntn-xyz commented Aug 8, 2021

That was my thinking. It's unfortunate that there is no direct mapping from H4+ to Gemini, but as long as there is some visual representation then it's probably "good enough" which is the best one can do for a lossy mapping (Markdown -> Gemtext definitely qualifies as such).

Since the space character is "mandatory" per the spec, then it should definitely be in there after three #s one way or another. It would technically be valid for a client to treat #### Heading as normal text instead of a heading.

I'd be glad to work on a patch for this unless you get to it first!

@tdemin tdemin added the bug Something isn't working label Aug 8, 2021
@tdemin tdemin added this to the 0.2.0 milestone Aug 8, 2021
@tdemin tdemin closed this as completed in 0be85fc Aug 9, 2021
tdemin added a commit that referenced this issue Sep 17, 2021
Gemini spec p. 5.5.1 used to only allow up to three #-s in a heading
before requiring a mandatory space. It changed to an optional space in
recent updates, allowing to no longer pad Markdown H4-H6.

As clients treat everything after ### a title continuation, the renderer
will now insert H4-H6 verbatim; the end-user behavior doesn't change as
extra space means nothing for a Gemtext renderer displaying the title in
a special way.

Relates to #1.

PS: Gemini spec doesn't appear to be properly versioned, saying the
latest version is 0.14.3, 2020-11-29. The discussion on #1 clearly shows
it used to be different a while ago.
@mntn-xyz
Copy link
Contributor Author

I'll leave a note for anyone referencing this issue in the future: I was mistaken, the current official spec says that the space is optional, but the gemtext "quick introduction" from the same site says it is mandatory. The authors of some clients may be operating on either an old version of the spec or this outdated gemtext guide, which is likely the source of the client issues I encountered.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

No branches or pull requests

2 participants