Code

Publish and Install Themes

You share a theme on GitHub, in a registry, or both. Users add a GitHub theme with one command. The add copies the files into the themes folder of the user, and the user owns the copy.

  • GitHub: users add your theme with github:<owner>/<repo>
  • Registries: a static registry.json file lists your themes
  • You own the copy: edit it, then use diff and update to merge upstream changes

Publish on GitHub

Repository Layout

Put the theme folder at the root of the repository:

a i v t t l l p a a p R L o h o a a a s s r E I r e k y y r s s e A C y m e o o t e e v D E - e n u u s t t i M N t . s t t / s s e E S h t . s s / / w . E e o t / f i s m m m d p o m / d e l m e h n a d - l s o t g e h k n s e s a t e / s k r o / / t b p o o . p r j ( ( . / . s w w p j o i i n s n t t g o h h n L L I I C C E E N N S S E E ) )

Release

  1. Check the theme:
aivoryd theme check .
  1. Make the release archive:
aivoryd theme pack .

The command writes harbor-1.0.0.aivory-theme.zip and prints its SHA-256.

  1. Make a Git tag that is equal to the version in theme.toml, with a v in front, for example v1.0.0.
  2. Make a GitHub release for the tag.
  3. Attach the .aivory-theme.zip file to the release.
  4. Add the topic aivory-theme to the repository, so that users can find it.
Note Put previews/desktop.png (1440x900) in the repository. Make it with demo data only. Never show real session content in a preview.

Licenses

  • Set an SPDX license in theme.toml, for example MIT.
  • Put a LICENSE file next to each font and image folder. Use fonts that you can share, for example fonts with the OFL license.
  • The validator rejects a font or an image without a license file.

Publish in a Registry

A registry is one static file registry.json plus one archive for each theme. You host them on GitHub, GitHub Pages or any HTTPS server.

Build the Registry

  1. Add registry.toml to your theme repository. It names the base URL where you publish the archives, and the theme folders:
name = "Mine"
base_url = "https://example.com/dl"

[[item]]
path = "themes/harbor"

Each [[item]] can also have title, preview and requires.

  1. Build the registry:
aivoryd registry build .

The command checks each theme. It writes registry.json and one archive for each theme into the folder dist. Use --out <OUT> to choose another folder. It puts the SHA-256 of each archive in the index.

  1. Publish the files of dist at the base URL, for example as GitHub release assets or on GitHub Pages.

Add a Theme

Add a theme from GitHub (the latest release, or a tag):

aivoryd theme add github:janedoe/aivory-theme-harbor
aivoryd theme add github:janedoe/[email protected]

The daemon downloads the archive, checks it and the theme, and copies the files into your themes folder. It records the source, the version and the hashes in theme.lock.

You can also add a theme in the desktop app:

  1. Open Settings > Display.
  2. Paste a GitHub link into the field.
  3. Read the name, the author, the license, the size and the hash in the dialog.
  4. Confirm the add.

Use Other Registries

aivoryd registry add @someone https://someone.github.io/aivory/registry.json
aivoryd registry list
aivoryd registry remove @someone

aivoryd registry list shows the registries and their items.

Change, Compare and Update

You own the copy of each theme. Edit it in the themes folder, or copy an installed theme to your own folder with aivoryd theme init my-theme --from <id>. The built-in looks are compiled into the app, so --from works for installed themes only.

Command What it does
aivoryd theme list shows your themes, their source, version and local changes
aivoryd theme diff <id> shows your edits and the upstream changes
aivoryd theme update <id> updates your copy at file level; a file that you edited stays
aivoryd theme remove <id> removes the theme; the app uses Minimal if it was the current theme

If your edit and an upstream change touch the same part of a file, update keeps your file and writes the upstream file next to it as <file>.upstream. Merge the two files, then delete the .upstream file.

Safety

Themes are data only
  • A theme contains no scripts. It has no network, file or clipboard access.
  • A theme reads only the session data that the app gives to all screens. It can only call the actions of the app, and only when you click or press a key.
  • The service checks each theme when you add it, when you update it and each time it loads it.
  • The service downloads only on your command, and only over HTTPS. The same version with another hash is an error.
  • Settings > Display always works. You can always go back to Minimal.

Next Steps

Make a Theme
Start your own theme
Theme Reference
Every field, component and error