One of the darlings of the Mac community is TextExpander from Smile. I think it’s #2 on my priority list of apps to install, right after 1Password. If you haven’t used TextExpander, the basic idea is that it allows you to type short abbreviations that trigger longer snippets of text to be spit out on screen. It does a lot more than that but that’s the fundamental utility it provides.
I wouldn’t use a Mac without it, but I’ve found a super nerdy substitute for the basic utility of TextExpander. It’s a free and Open source project by Federico Terzi github.com/… called espanso. When I say nerdy, I mean it. Tighten your propeller beanies, kids.
Espanso is available from espanso.org for Windows, Mac and Linux. Installation of espanso is slightly different on the three platforms, of course, and I’ll be talking about this from the Mac perspective. The documentation on installation and configuration is very good on the espanso website so I’m sure if you’re a Linux or Windows girl you won’t have any trouble figuring it out.
Installation of espanso
I’m not going to go through the sequence of commands line by line because the espanso instructions do it beautifully, but I’ll describe the process of installation and use of espanso to get you excited about using it.
We’ve talked a few times on the NosillaCast about using package managers to install nerdy stuff on the Mac using the Terminal, and we usually talk about using Homebrew. espanso for Mac is installed using Homebrew. If you haven’t used Homebrew before, it’s crazy easy (if a bit nerdy). Once you follow the one-line instruction to install Homebrew itself from the Terminal, from then on you simply type brew install followed by the name of the software you want to install.
For some apps (like espanso) you have to “add a tap” to Homebrew before you can install the app you need. Adding a tap just means to add more repositories for Homebrew to look in to find the tool you want.
To install espanso you type in two separate commands in the Terminal to add the tap and then install espanso. As with TextExpander, espanso also requires you to enable Accessibility access in System Preferences and then you’re ready to play with espanso. The instructions are so detailed on the espanso.org website that Federico even spoon-feeds you the Accessibility settings you need to enable.
Once espanso is installed, it will show up as a menu bar icon. 99% of what you’ll do configuring espanso will be done from the Terminal, so the menu bar app doesn’t do a whole lot. But what it does do is super important and we’ll get to that in a bit.
YAML Configuration File
In order for espanso to know what snippets of text you’d like to expand, you have to provide a file with the expansions. espanso does this with a configuration file in the YAML format. For people who like to know acronyms, YAML is a recursive acronym that stands for YAML Ain’t Markup Language, and it’s simply a specific way to format text. YAML has rules about what indents mean and what quotes mean and how to write comments. The espanso instructions give you an example configuration file to follow and as long as you follow the format you’ll have no problem with it.
The default configuration file is buried deep in your user Library Preferences directory (/Users/user/Library/Preferences/), which is a bit of a pain to remember every time you need to edit the file. But if you’re happy on the command line, you don’t have to remember where the configuration file lives. Simply type espanso edit in at the command line and the configuration file will open in the default editor for your operating system: nano for UNIX-based systems like macOS and Linux, or Notepad if you’re in Windows. When you save the configuration file, espanso will restart itself automatically.
The syntax of the configuration file for espanso is pretty simple. Comments are made using the # (hash, number, octothorp symbol), and making comments is a good way to help you organize your text expansions. In espanso these expanded pieces of text are called matches, and matches are generated using is called a trigger. If you want a match of “Hi There” to be triggered by “:espanso” you would write it like this:
- trigger: ":espanso"
replace: "Hi There"
In this example, the default trigger symbol suggested by Federico is a colon : before the match but he points out that on macOS, this can conflict with macOS’s Keyboard Shortcuts so you could get replicated expansions. He suggests using a backslash / before your match instead if you use Keyboard Shortcuts.
In the example file, they include the simple text replacement I just described, and also two examples that are a bit more complicated to show off the advanced power of espanso. I don’t want to try to read it out loud to you because it is a bit complicated. The examples demonstrate how you can automatically have today’s date entered with a trigger and issue shell commands from a trigger in espanso.
If you’re a big ol’ nerd, you can edit this config file using your favorite command-line editor like nano or pico, or you can open the file from the Finder using a GUI editor like CotEditor or Atom or even TextEdit if you like.
I created a couple of matches myself for my name and my signature. The only tricky bit was learning to use \n to create a new line in my signature and I was good to go.
Extend espanso With Packages
The community has created packages that can be installed in espanso to extend its library of matches. Installing a package is super simple. For example, if you’d like to install the basic emoji package use the command:
espanso install basic-emojis
Espanso has a hub where you can find packages to fit your needs at hub.espanso.org/…. They’ve got useful packages like Excel formulas, math symbols, and medical documentation, but also one to generate random dad jokes. There’s even a package for Bart’s favorite command-line weather tool, wttr.
Click on a package in the hub and it will display the matches you get in this particular package. Note that all packages have to be hosted on Github, which means if you like one but want to modify it you can fork it and make it your own. I installed the package for Mac symbols like command, control, and escape and now I can easily type them with a quick keystroke.
⇧ ⌘ ⌃ ← ⇪ ⎋ ⌫ ⎋ ⌃ ↵
One thing baffled me for a long time, and that was how to see into the packages I had installed. They didn’t show up in the default config file and not in the user directory next to it. I could list them with espanso package list, and it would tell me what ones I had installed, but where were they located on my drive? Without knowing where they were, I couldn’t easily jump in and see what matches were available to me with a particular package. Sure I could go to espanso.org to find the link to the hub to find the link to the package to find the link to the documentation… but I wanted to be able to do it locally. The documentation on packages gave me no clues.
I resorted to the espanso sub-reddit and found someone asking the same question. In Terminal if you enter espanso path it will reveal the location of the config file we’ve been talking about, along with the location of the packages you have installed and the configuration data you have for espanso. The packages live in your user Library inside Preferences/Application Support.
allison@MBP-16 ~ % espanso path
Config: /Users/allison/Library/Preferences/espanso
Packages: /Users/allison/Library/Application Support/espanso/packages
Data: /Users/allison/Library/Application Support/espanso
Once I knew where the packages were, I could open their YAML configuration files and see what they included and even modify them if I liked. One of the main reasons I wanted to do this was that the all-emojis package I’d installed wasn’t working properly and I wanted to figure out why. The match for “:neckbeard:” that was shown on the documentation page in the espanso hub wasn’t doing a darn thing. Once I found the config file, I was able to search for neckbeard and confirm it wasn’t IN the config file. I felt better knowing that it wasn’t me doing something dumb, and guess what else? I can ADD the neckbeard emoji into the package and make it work if I want to.
Application-Specific Configurations
There are times that you have an application where you want to have very specific matches, and espanso provides a mechanism for that. You create an application-specific configuration file, and then in your main configuration file, you create a filter for that application. The syntax is simple, and well-described in the documentation for espanso.
More to Like
Have you ever been in a situation where TextExpander expands a snippet but in that particular instance that’s not what you wanted? Happened to me the other day when I was trying to type 501 (c) and the c in parentheses kept changing to a copyright symbol ©. When this happens, you have to sneak up on TextExpander by typing the second half of what you want, using the arrow keys to get to the front of it, and then typing in the beginning bit.
With espanso though, simply hitting backspace after espanso triggers a match reverses the match and puts back the typed trigger text. I love this feature! I discovered it on my own when I instinctively hit backspace after a match expanded that I didn’t want.
If you know ahead of time that you want to type something that will trigger a match in espanso, simply double press the Option key to temporarily disable espanso. Double-tap it again to re-enable espanso. You’ll even get a nice little notification from espanso telling you that you’ve disabled and enabled it. I really wish TextExpander had this feature.
Remember I explained that espanso had a very limited menu bar app? One of its primary features is to turn from a bold lower case e, to a greyed out e when it’s disabled. You can tell at a glance if espanso is disabled. If you make an edit to your configuration file from a GUI text editor, you can also use the menu bar app to reload the configuration file. Of course, if you’re editing from the command line, you would just type espanso restart.
espanso very politely disables itself (and notifies you of such) when your browser has a password field open. This is caused by the macOS security feature known as SecureInput. It’s quick and elegant, and remember you can glance at that menu bar to be sure espanso is covering its eyes while you type in your private data.
As a result, espanso will not work in those situations, and espanso will trigger a notification (as well as logging it) to warn the user if an app triggers SecureInput. In my limited experience with espanso, it seemed to re-enable itself more consistently than TextExpander does. When TextExpander gets confused about SecureInput, you can sometimes shut down every single application and TextExpander still won’t re-enable itself. The only thing I know to do is to actually reboot the Mac. Like I said I don’t have a lot of experience with espanso but TextExpander got confused just this week while espanso was fine.
One of the things that nerds will appreciate about espanso is your ability to modify the application’s behavior to your heart’s content. Don’t like getting notifications? Disable them from the command line. Like notifications but don’t want to see just the SecureInput notification? You can disable just that one. Don’t like using the alt key to temporarily disable espanso? You can change that too. If you don’t like having the menu bar icon, you can disable it in your configuration file with show_icon: false.
Bottom Line
I think espanso is a delightful contribution to the community and especially fun if you’re of the nerdy persuasion. If you’ve always wanted to do something nerdy, this is a pretty easy way to get your feet wet. The instructions on the espanso site are very clear and if you don’t understand a particular option, just skip it! I skipped a lot of the options they described and just used the ones that made sense to me.
espanso is also great if you’ve got limited funds and can’t afford to pay for TextExpander. Don’t get me wrong in my endorsement of TextExpander, it’s still going to be my #2 most important app. But guess what? I can have TextExpander AND espanso on my system and enjoy the best of both worlds. Check it out at espanso.org and if you like it, give the developer a tip!