DOCSEARCHbyAlgolia
Submit Docs

Espanso Documentation

website·Indexed 38 days ago

https://espanso.org/docs/get-started/

Documentation for Espanso, a text expander that uses YAML files to manage configurations. It features static and dynamic matches, regex triggers, variable injection, and forms. Supports Windows 10+, macOS 10.13+, and Linux (X11 and Wayland). Includes guides on package creation, CLI usage, and statistics tracking introduced in v2.4.0.

Tokens
18.3K
Snippets
153
Records
190
Agent score
73%

What's inside Espanso

  1. Overview of Espanso text expansion

    Espanso is an open-source, cross-platform text expander for Windows, Linux, and macOS. It works by detecting a specific keyword typed by the user and automatically replacing it with a predefined snippet of text. It is licensed under GPL-3 and uses a file-based configuration system.

  2. Understand the Espanso configuration structure

    Espanso separates configuration into two primary directories:

    1. config/: Defines HOW Espanso behaves (expansion speed, UI shortcuts, etc.). The default.yml file is the base profile used when no other app-specific configuration is active.
    2. match/: Defines WHAT Espanso expands. This contains snippet definitions and global variables. For basic use-cases, snippets should be placed in base.yml.

  3. Install Espanso on Windows

    Espanso is compatible with Windows 10 or later on x64 architecture. It can be installed via a standalone installer, run as a portable application via a ZIP archive, or installed using a Windows package manager.

  4. Organize matches using multiple files in the match directory

    Espanso automatically loads all YAML files (with .yml or .yaml extensions) located in the $CONFIG/match directory and its sub-folders. This allows you to split your snippets into multiple 'match sets' instead of putting everything in base.yml.

    Important Exception: Any file starting with an underscore (_) is ignored by the automatic loader and will not be loaded unless explicitly imported or included.

    # Example: $CONFIG/match/emails.yml
matches:
  - trigger: ":sig"
    replace: "Best, John"
  
  - trigger: ":sig"
    replace: "All the best, John"

  5. Publish a public package to the Espanso Hub

    To share a package publicly via the Espanso Hub:

    1. Fork the Espanso Hub repository.
    2. Clone your fork locally.
    3. In the packages/ directory, create a new folder named after your package (e.g., packages/simple-package).
    4. Inside that folder, create a versioned subfolder (e.g., packages/simple-package/0.1.0) containing package.yml, _manifest.yml, and README.md.
    5. Customize these files with your snippets and metadata.
    6. Commit and push changes to your fork, then open a Pull Request to the original espanso/hub repository for review.

  6. Undo an accidental expansion with Backspace

    If you accidentally trigger an expansion, pressing the BACKSPACE key immediately after the expansion will revert the action and recover the trigger string. This behavior can be disabled in the config/default.yml file.
    undo_backspace: false

  7. Create a basic text replacement match

    To create a snippet, add a match to the matches list in $CONFIG/match/base.yml. A match consists of a trigger (the keyword you type) and a replace (the resulting text).

    Note: Use spaces for indentation to ensure valid YAML syntax. Espanso automatically reloads configuration upon saving the file.

    matches:
  - trigger: ":br"
    replace: "Best Regards,\nJon Snow"

  8. Install Espanso on Ubuntu/Debian (X11)

    For Debian-based systems running X11, the recommended method is using the .deb package. You can verify the package integrity using the SHA256 hash provided in the espanso-debian-x11-amd64-sha256.txt file on the GitHub Releases page.
    # Download the package
wget https://github.com/espanso/espanso/releases/latest/download/espanso-debian-x11-amd64.deb

# Install the package
sudo apt install ./espanso-debian-x11-amd64.deb

  9. Install a specific version of an Espanso package

    While Espanso installs the latest version by default, you can target a specific version of a package using the --version flag.
    espanso install <package_name> --version <package_version>

# Example
espanso install html-utils-package --version 0.1.0

  11. Install Espanso packages from generic Git repositories

    Espanso can install packages from any Git repository that follows the Package Specification. Unlike GitHub/GitLab integrations, installing from a generic Git repository requires the git command to be installed and available in the system PATH, as Espanso uses git clone to fetch the package.
    espanso install dummy-package --git https://github.com/espanso/dummy-repository --external

  12. Install Espanso on macOS via App Bundle

    Espanso supports macOS 10.13 or greater on both Intel and Apple Silicon architectures. To install as a traditional app bundle, download the Universal binary disk image (.dmg), open it, and drag the Espanso application into the /Applications folder.