💾 Archived View for thfr.info › gemini › pages-best-practices.gmi captured on 2024-05-26 at 14:52:06. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

My Personal Thoughts on Best Practices for Gemini Pages

Just a loose, evolving collection of some thoughts on the Do's and Dont's for Gemini capsules.

Author: thfr

Date: 2021-03-11

Last Updated: 2021-03-11

Don't: Terminal Control Codes - Yes, That Means No Color for Preformatted Text!

Using terminal control codes in Gemtext at all was a hack from the beginning.

Was never in the spec.
Horribly intransparent for users.
Varying implementation in different terminals, clients. E.g. no baseline support in GUIs or Ncurses without a specific parser.
Would require a complex parser for support outside of a terminal that just processes them.
SECURITY RISK! There are control codes for more than just colors. They can mess up your terminal, or worse!

It would be best to that all clients just filter out these codes. [Note to self: insert the reference from ML list discussion here.] For such clients, and all those that don't support it to begin with, the control codes are just waste of bandwidth.

Don't Replace Your Page Heading with ASCII ART

ASCII art can be a nice way to add a bit of flavor to your webpage. But please, don't let it interfere with the actual, readable and processable content!

Clients can't (easily) get characters out of ASCII art, but they may want to store the web page title e.g. for bookmarks, subscriptions.
Visually impaired users that use Text-to-Speech will not be able to get anything from ASCII art other than garbage.

To clarify - I don't want you to get rid of your ASCII art (only the color, see above), but if the title of your webpage is only readable in ASCII art display, then please consider spelling the title out in a heading.

Don't Stuff Your Page with Basic Navigation Controls

I mean custom implementations of "back", "up", "next", "previous", "root" in the domain's file hierarchy. Yes, I've been guilty of doing this myself for playonbsd.com.

These basic navigation steps should best be left to the client. Client software should be encouraged to offer these navigation features which are rather simple to implement.

Gemini Client Design - Navigation

Gemini client navigation (by Solderpunk)

Do: Use the Format YYYY-MM-DD [Timezone] for Serial Content (Gemlogs primarily)

An easy way to make your content more discoverable.

Gemini companion spec for subscriptions

While not part of the spec, some clients may support parsing a longer time format such that it's easier to server multiple entries per day: YYYY-MM-DD HH:MM [Timezone]

Do: Add Timezone to your Gemini Subscription Links

I would encourage this as it can help clients to better update content. It's often impossible to know what timezone you mean - don't assume, don't make an 'ass' out of 'u' and 'me'. Gemini (like the WWW) should be an international effort.

Do: Use Headings to Structure Longer Documents

Whether it's a long essay or a long list of links of varying categories, you can assist the user with navigation and readability by making good use of the 3 levels of headings. Some clients like Lagrange offer an outline sidebar to assist in page navigation which depends on the page having meaningful headings.

The Gemini spec is a good example of this.

Do: Consider Sharing your Server's Fingerprint Somewhere Out-of-Band

Gemini's baseline security model is "Trust On First Use" (TOFU), which should (!) guarantee that you are connected to the same host as before under the same domain, unless there is a notification of a change in certs. The biggest limitation is that the first connection to the server has to blindly accept whatever cert is presented; making this at least a (practically narrow) window of opportunity for an attacker.

One way to work around this limitation is for users to compare the cert's fingerprint to a fingerprint received out-of-band, via a credible channel. This can be a different web resource by the same person, the person's business cards, social media etc.

Obviously, users can't do this for every domain they interact with. Practically, a user may have a few pages that they interact with where the privacy of the connection is more important, e.g. for sensitive information, personal data. In these cases, it would be good to offer a way to confirm the server identity as I describe here.

Don't Link to Directories without Including the Trailing '/'

If an address to a directory is provided to the server without the trailing '/', the server will respond with a '3x' redirect to the address with the trailing '/'. For example:

gemini://thfr.info/gemini ==> gemini://thfr.info/gemini/

As a result, the interaction now has to process 2 requests, which almost doubles the bandwidth need.

So, be nice to your users and their clients and include the '/' in links to directories.

----------------

~thfr