Espanso

Introduction

This page covers my notes for the Espanso text-expander.

View my current espanso configuration files.

Configuration:

File-based configuration, under the espanso directory (dependant on OS):

OSConfiguration path
Windows%APPDATA%\espanso
Linux$XDG_CONFIG_HOME/espanso
MacOS$HOME/Library/Application Support/espanso

The config/default.yml file contains the global espanso configuration settings.

Matches:

The match/base.yml file contains the find/replace matches:

global_vars:
 - name: <variable_name>
   type: echo
   params:
     echo: "Value"
 ...

matches:
 - trigger: "<text to trigger the expansion>"
   replace: "<replacement text>"
 ...

Additional match configuration files can be created, and linked to a parent configuration (match/<filename>.yml).

name: <filename>
parent: default

matches:
 ...

Configuration keys:

  • trigger: <value>
    Defines the trigger text.
  • replace: <value>
    Defines the replacement text.
  • propogate_case: <true/false>
    Propogate the case of the trigger?
    (e.g. alh → although, Alh → Although, ALH → ALTHOUGH)
  • uppercase_style: <capitalize_words>
    If the replacement text contains multiple words and you want to capitalise each word.
  • word: <true/false>
    Match on whole word?
  • image_path: <path/to/image.png>
    Expand text into images.
  • vars: <...>
    Allows for dynamic matches, a variable can be used within the scope of the trigger/match {{⁠var_name⁠}}.

Variable types:

  • choice
    Used in conjunction with the params type to bring up a selection box to pick values from.
  • clipboard
    Allows you to trigger/replace with what’s in the OS clipboard. This can be a very powerful type as you can use and replace what’s in the clipboard.
  • date
    Can be used to include date and time information in a match.
  • echo
    Creates a variable containing a fixed value, which can then be used within a trigger.
  • form
    Create a dialog window/template template which can accept multiple arguments.
  • html
    Support HTML styling for the output, e.g. <b>bold</b>, <em>italic</em>, etc.
  • label
    This allows a description to be provided for the trigger within the search dialog.
  • markdown
    Supports markdown styling for output, e.g. *bold*, **italic**, etc.
  • match
    Allows you to call an existing trigger.
  • name
    Used to name a variable.
  • params
    Some variable types require extra parameters to function (e.g. date, choice, args, etc), these are supplied beneath this key.
  • random
    Used in conjunction with choices params type to select a random value from a list.
  • regex
    A regex match based trigger. e.g. :greet\\d would match “greet” plus any single digit.
  • shell
    Used in conjunction with params type to run a shell command.

Parameters:

  • cmd
    Configure the shell-command you want to execute.
  • format
    Used for the date var type (determines how it’s rendered).
  • locale
    Used to override the default system-preference locale (must be supplied in BCP47 format).
  • offset
    Used to offset the date var type (expressed in seconds).
  • shell
    Configure the shell to use, the default shell depends on the OS (italicised below), the following are supported:
    • Windows: powershell, cmd, wsl
    • Linux: bash, bash
    • MacOS: sh, bash
  • trim
    By default the trim option is enabled to remove excess spaces/new-lines. This can be disabled by setting trim: false.

Extra:

  • global_vars
    This is a configuration option (at the same level as the matches: key). This allows for globally scoped variables to be used within other replace/match/vars.

  • imports
    This is a configuration option (at the same level as the matches: key). This allows for importing external match configuration files from external locations (such as networked drives).

    imports:
 - "/path/to/other/matches.yml"
 - "/path/to/external/drive/matches.yml"

  • Cursor hints
    If you want the cursor to be placed in a specific location within the replacement text, that is supported by adding $|$ at the location you want the cursor to be placed:

     - trigger: ":html"
   replace: "<html>$|$</html>

  • Match Disambiguation
    If you configure the same match trigger values, then espanso will bring up a dialog box to allow you to chose the desired one.

Out-of-scope:

  • Espanso doesn’t currently support sending META-keys (e.g. Ctrl, Alt, Tab, Esc, Win/Super, Return keys).
    See Issue#286.

Further reading:

Responses (0) You can respond to this post using Webmentions.