Troubleshooting & How-Tos

Add a Gemini filetype to Gnome

Gnome (and possibly other desktop environments) will be able to recognize local Gemtext files as text files by their content, but has no idea what to make of a .gmi file on a network share where it’s only looking at the extension.

Solution: Add the mimetype to Gnome.

As an added bonus, you can assign your favorite Gemini client (if Gnome knows about it) to open Gemtext files by default, and set up specific text editors and/or other clients as alternate applications.

  1. Create a gemini.xml file to define the type.
<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
  <mime-type type="text/gemini">
    <comment>Gemtext</comment>
    <glob pattern="*.gmi"/>
  </mime-type>
</mime-info>
  1. If you want to add it for all users on the system, put it in /usr/share/mime/packages/, or if you want to just add it for yourself, put it in ~/.local/share/mime/packages

  2. Run update-mime-database ~/.local/share/mime or sudo update-mime-database /usr/share/mime depending on whether you put it in your local or systemwide folder.

  3. Browse to a folder with your Gemini files. Right-click one of them and check properties: it should show the type as Gemtext (text/gemini).

  4. Assign a gemini client and/or text editor to open the files using the “Open With Other Application” menu item or the “Open With” tab in the properties dialog for any Gemtext file.

Adding your favorite client to the list

Depending on how you installed your Gemini client and whether the installer or package does it itself, your client might not show up in the list. In this case you probably need to add a .desktop file defining the application and what filetypes and schemes it can handle.

For instance:

  • Lagrange’s Flatpak package will install its .desktop file.
  • Kristall will install a .desktop file (and the mime information!) if you run make install.
  • Amfora offers a binary download and a .desktop file from its Github page.
  1. Find or create a .desktop file for your client. It should look something like this (with variations for other protocol schemes or filetypes it might be able to accept.
[Desktop Entry]
Type=Application
Name=ExampleClient
GenericName=Gemini Browser
Categories=Network;WebBrowser;
Keywords=gemini
Terminal=false
Exec=example %u
MimeType=x-scheme-handler/gemini;text/gemini;
  1. If you want to add it for all users on the system, put it in /usr/share/applications, or if you want to just add it for yourself, put it in ~/.local/share/applications

  2. Run update-desktop-database ~/.local/share/applications or sudo update-desktop-database /usr/share/applications depending on whether you put it in your local or systemwide folder.

Now you should be able to go back and open those files!

Sources: Gnome system administration guide

And thanks to @edavies@octodon.social for pointing out that you may need to add the .desktop file to make the application appear in the list!