A text expander replaces predefined abbreviations with stored text modules. One example of this is wkr, which expands to With kind regards after entering the abbreviation. The AutoKey [1] tool I used until a year ago was no longer fit for purpose because it only works on Linux and only on X11 – which leaves Wayland out in the cold.

As an alternative to AutoKey, Espanso [2] has been available since 2019, and it goes beyond simply replacing abbreviations in texts. The text expander, written in Rust, runs on Linux, macOS, and Windows. You can install the application on Linux for Debian, Ubuntu, and other derivatives using a DEB package or as a DIY binary package. There are also AppImages and packages for Snap. Only the Arch User Repository (AUR) wants you to build Espanso directly. If your distribution is not directly supported, you can use the AppImage or build a package yourself. The developers are looking to extend this support over time.

Start by running the echo $XDG_SESSION_TYPE command to check whether the system uses X11 or Wayland as the session type. Depending on the result, you may need to select different packages or source code in each case, as described in the installation instructions [3]. Listing 1 shows the setup of the DEB package under X11. To do this, first download the package, then run apt to install and make sure that the installation worked (lines 1 to 3). Finally, introduce the Espanso service to systemd (line 4).

01 $ wget https://github.com/federico-terzi/espanso/releases/download/v2.1.7-beta/espanso-debian-x11-amd64.deb
02 $ sudo apt install ./espanso-debian-x11-amd64.deb
03 $ espanso status
04 $ espanso service register
05 service file already exists, this operation will overwrite it
06 creating service file in "~/.config/systemd/user/espanso.service"
07 enabling systemd service
08 service registered correctly

Then run the espanso start command to call the tool. After the welcome window closes, there is no trace sign of Espanso on the Linux desktop, whereas an icon appears in the control bar on macOS and Windows. An overview of the commands you can use to control Espanso is provided by espanso -h (Figure 1).

Figure 1: You can use the -h or --help parameters to investigate the available options.

In its function as a text expander, Espanso waits for you to enter a keyword in the form :keyword and substitutes it for the stored text. For example, if you type :espanso, the correct response is Hi there!. Espanso replaces abbreviations everywhere you can write them, including in the shell.

You configure the application in several files below ~/.config/espanso. The default.yml file in the config/ folder contains global settings that you enable by removing the preceding hashtag. But be careful: YAML does not forgive mistakes with indentations.

Configuration in YAML

You can use the espanso edit command to open the configuration file. If possible, the string to be replaced should not contain nonstandard characters. Replacing them works in some apps, but not in others. Because the configuration file is also written in YAML, you need to pay attention to the indentations again. Just follow the examples provided.

When you save your edits, Espanso shows you a pop-up window where you are prompted to confirm the action. If you made a mistake, a message will tell you at which position in which line this is (Figure 2).

Figure 2: If an error occurs during an edit, you get a message after saving showing you the line and position of the error.

The match/ folder is where you specify what you want Espanso to replace and what with. The tool gives you some simple examples of replacements (Figure 3) in the /match/base.yml file. Replacements are defined by a pair of trigger and replace values. trigger denotes the string that triggers the replacement, while replace contains the replacement itself. A simple example looks something like this:

- trigger: ":kr"
  replace: "Kind regards,"

Figure 3: The base.yml file contains some examples. You can extend them with your own replacements or create themed files yourself.

Another example, which often occurs at the end of letters and emails, gives you two lines of output.

- trigger: ":lp"
  replace: "Love,/nPeter"

In addition to /n for creating a new line, YAML uses two operators, | and >, as soon as more than two lines come into play. If you use | as the first operand after replace, Espanso outputs the text exactly as you write it. In line with this, the three lines from Listing 2 are also rendered as three lines. If you replace | with > here, the application writes the replacement text in a single line. You can learn more about these scalars in YAML on Stack Overflow [4].

- trigger: "three"
  replace: |
    This is replaced
    just like it is written
    here

Static or Dynamic?

Espanso distinguishes between static and dynamic replacements. The examples described thus far belong to the static category; their output always remains the same. A typical example of a dynamic replacement, on the other hand, is outputting the current time of day. Espanso uses variables to let you do this.

The example from Listing 3 introduces the time variable in the replacement. I chose the name, declared it to be a date type, and added matching parameters for the output. A similar dynamic example that already exists in /match/base.yml gives you the date output. The replacement can be quickly adapted to, say, a UK date format. To do this, change the format:"%m/%d/%Y" string to format:"%d/%m/%Y". If you now enter :date, you will see the day and month in the typical UK order.

- trigger: ":now"
  replace: "It's {{time}}"
  vars:
    - name: time
      type: date
      params:
        format: "%H:%M"

Espanso lets you define both short replacement texts and whole sentences or even longer text blocks. To avoid the standard configuration becoming too confusing, it is a good idea to create several YAML files such as match/emails.yml or match/code.yml as the number of text modules increases.

Global Variables

One reason to create a new YAML file is to provide global variables that you can then use in multiple replacements. You define the global variables at the top of a YAML file. They are then available for all replacements defined in this file and its subfiles. Espanso also proves useful if you often mistype certain words, for example, if you often type additinal instead of additional. The true parameter is used here, as you can see from the detailed documentation [5].

If you like to write code, Espanso will help you with that, too. I'm sure you will find out how to replace the HTML tag pair <div></div>, for example, on your own based on what we have looked at so far. But how do you move the cursor into the middle instead of to the end? The $|$ abbreviation is used for this purpose, as shown by the first two lines in Listing 4.

01 - trigger: ":div"
02   replace: "<div>$|$</div>"
03 - trigger: ":quote"
04   replace: "Three can keep a secret, if two of them are dead."
05 - trigger: ":quote"
06   replace: "To be or not to be, that is the question."
07 - trigger: ":quote"
08   replace: "If you want something done right, do it yourself."
09 - trigger: ":cat"
10   image_path: "/PATH/TO/IMAGE.png"

It is also useful to be able to specify multiple replacements with identical triggers using the quote parameter (Listing 4, lines 3 to 8). If you enter the :quote trigger, you can select which quote you want to use (Figure 4). For example, you can use it to implement multiple salutations in different languages. If required, Espanso can also trigger images (line 9 and 10) and create various forms [6].

Figure 4: In Espanso, multiple substitutions can have the same trigger. The :quote trigger shows a window where you select what you want by pressing a keyboard shortcut.