💾 Archived View for blakes.dev › themepacks.gmi captured on 2024-08-24 at 23:22:43. Gemini links have been rewritten to link to archived content

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

Themepack spec draft

This is a rough draft of a specification for "theme packs" geared towards Lagrange, but they can be reused by other apps as well.

example.themepack

A Themepack file:

is written in TOML
has the traditional file extension .themepack
uses the MIME type application/vnd.lagrange.themepack+toml ("application" used since it configures an application)
can be automatically applied when clicked, under some circumstances

A Themepack ZIP pack:

contains only .themepack files and a recommended themepacks.toml index/behavior file
has the traditional file extension .themepacks.zip
uses the MIME type application/vnd.lagrange.themepack+zip
does not automatically apply; enhanced linking behavior can be used instead

Handling by Lagrange

Should Theme Packs be implemented in Lagrange, the following should apply.

First, a link on a page to a .themepack file is clicked and background loading, like done for media, is attempted. If the MIME type does not match what was expected, load it as a regular link.

If the contents are valid (see "Themepack TOML" section below), no external resources like fonts or images are requested, and the "domain" covers both the linking page and the linked themepack file, the pack is automatically applied. The current page should not be reloaded, but it should be restyled immediately.

Other clients may handle themepack file links in a similar way.

Themepack TOML Format

domain (REQUIRED, at root) — The "prefix" that the theme applies to.

If this is omitted, it CANNOT be automatically applied. This may be useful to add global themes in the future but this spec is not built to handle that case.

The domain prefix MUST include the hostname that it applies to. If no scheme (i.e. spartan://) is provided, Gemini should be assumed as the default. If no port is provided, it should be assumed to be the default port of the scheme used (so, 1965 by default). Finally, if no path is provided, the theme applies to the entire site, EXCEPT areas with more specifically applied themes or "user" areas (Lagrange considers at least /users/ and /~... prefixes).

[lagrange.theme]

site_name (optional) — The displayed name of the site.
favicon (optional, 1 character) — The default icon to display for the site.

A bookmark icon will override this. Additionally, unlike bookmark icons, this applies to the "domain" of the site only, instead of the entire site.

colors (optional, a 3 element array of string color codes) — The three base colors to build the theme from.

Primary, accent/secondary, and tertiary for good measure.

This does not guarantee your exact chosen color will appear, but the greatest chance for that lies with the primary color.

[lagrange.menu]

This section defines a menubar. I don't know if this will ever be used, but a man can dream.

Keys (names) are the displayed link names, and the values are the link destinations. Offsite or off-"domain" links may show icons, even if the links don't by default.

Extra whitespace in link names should be minimized to make menubar links more distinct from each other.