Espanso Setup and TextBlaze Migration Report

Estimated reading time at 200 wpm: 7 minutes

This post documents the transition from TextBlaze to Espanso on a BigLinux system, detailing the technical hurdles overcome and the final configuration logic. The plan is then to run Espanso on W11.

1. Espanso vs. TextBlaze: Key Differences

While both tools serve the same goal, the philosophy of use is different:

• Privacy & Ownership: TextBlaze stores your snippets on their servers. Espanso stores them locally on your hard drive. You own the data, and it works without an internet connection.
• Interface: TextBlaze relies on a graphical dashboard and browser extension menus. Espanso is “headless”—it has no permanent window. It lives in the background and only interacts with you through the text you type.
• The “Menu” Factor: TextBlaze sometimes prompts with a menu to confirm an expansion. Espanso is designed for instant expansion. If you type the trigger, the text appears. No clicking required.
• Expansion Method: TextBlaze injects text via a running application or browser extension. If TextBlaze app is not active then nothing happens. If not in a browser nothing happens there. Espanso uses system-level “simulated typing” or “clipboard injection,” making it truly universal across every piece of software on your computer. It’s set to run quietly in the background, across everything.
• Cost: Espanso is free and open-source software (FOSS). There are no paid tiers, subscriptions, or limits on the number of snippets you can create. TextBlaze will cost between $USD 2.99 and $6.99 per month billed yearly. Well, it may not seem like a lot ‘per month’. I’d prefer to keep that money for food. But in a free and democratic society everybody has choice!

2. The Critical First Step: Identifying the Environment

The most important lesson learned during this setup was that the choice of software depends entirely on the “Display Server” the computer uses.

• Wayland: The modern, more secure, but more restrictive system.
• X11: The older, more flexible system that BigLinux defaults to in many configurations.

The Diagnostic Command:

echo $XDG_SESSION_TYPE

In this case, the result was x11. Every “Wayland” version of the software we tried failed because it was looking for a “Compositor” that didn’t exist in an X11 session.

3. Why Espanso?

The move from TextBlaze was driven by the need for a native, system-wide solution on Linux that:

1. Stays out of the way: No pop-up menus or “option” boxes.
2. Works everywhere: In LibreOffice, the terminal, and web browsers.
3. Cross-Platform: The configuration can be moved to Windows 11 later.
4. Ownership: Your shortcuts live on your actual computer, not a cloud server.

4. The Migration Journey (TextBlaze to Espanso)

TextBlaze uses a proprietary format, while Espanso uses YAML (a text-based list format).

Learning to Speak “YAML”

YAML sounds intimidating, but it’s really just a very organised list. The biggest hurdle? YAML hates “Tabs.” It only likes spaces. Once we configured the editor (KWrite) to replace Tabs with Spaces automatically, the “brain” started to come alive.

• Multi-line Text: We used the “Pipe” symbol (|) to handle long-form medical reports and legal drafting while preserving paragraph breaks.
• Timestamps: We translated the logic to generate real-time session stamps (e.g., /date for the current time).

5. The LibreOffice Challenge

If you’ve ever used text expanders in professional word processors, you know they can be “fussy.” Initially, LibreOffice would show both the trigger and the replacement (e.g., /knKael'Nyrin).

The “Surgical” Fix

We solved this by telling Espanso to use the Clipboard. Instead of “typing” the letters one by one, Espanso now “pastes” them. Combined with a tiny “delay” to let the software breathe, it is now cleaner, faster, and much more reliable for the complex reports I draft.

6. Visual Management, Backups, and the GUI Warning

I even experimented with a “Graphical Interface” (a visual window to manage the shortcuts) found in the BigStore. While it looked nice, “Fortune Favours the Bold” comes with a warning. Because everything in Espanso is just a file, I became “invincible” only after creating a backup.

• Strategy: Copy the entire espanso folder (found at .config/espanso/) to your Documents before experimenting. If a GUI messes up a setting, you just swap the old file back in.
• The Keyboard Trap: Most GUIs default to a us (United States) keyboard layout. If you don’t manually switch this to gb, your symbols like " and @ will be swapped when Espanso expands a shortcut.
• Comment Stripping: Many GUIs rewrite the entire file, which can erase the # headers used to organise folders.
• Setting Overwrites: A GUI might reset our custom backend: clipboard setting back to auto.
• Variable Support: GUIs often struggle with complex date math.

Recommendation: The real power lies in the simple text files. Treat the GUI as a viewer; for complex work, KWrite remains the safest tool.

7. The Windows 11 Sync and the “Rendering Error”

Moving the “brain” to a Windows 11 laptop was the final test. I encountered a “Rendering Error” because the Windows version couldn’t find my date variable definition. But this is a minor detour. Details will follow.

8. Tips for Editing Your YAML “Brain”

Because Espanso relies on a very strict file format (YAML), a tiny mistake can stop the whole system. Here is how to edit your shortcuts without breaking the engine:

The “No-Tabs” Rule

This is the most common cause of errors. In editors like KWrite or Notepad, hitting the “Tab” key inserts a specific character that YAML cannot read. Always use the Spacebar for indenting.

Respect the Indentation

Think of the file as an outline. The trigger and replace lines must be indented by exactly two spaces. If you add extra spaces or forget them, the computer won’t know where one shortcut ends and the next begins.

The Magic of the “Pipe” (|)

When you have a long professional report or a legal template, you can’t just type it all on one line. Use the replace: | syntax. The vertical bar tells Espanso: “Everything below this is part of one big block of text.” It preserves your paragraphs and lists perfectly.

9. The Technical Reference (The Code)

The “Brains” (default.yml)

Located in the config folder.

# This tells the computer to use a UK layout
keyboard_layout:
  layout: "gb"

# This ensures that LibreOffice doesn't glitch by using a "copy-paste" method
backend: clipboard

# These add tiny delays so the computer has time to react
backspace_limit: 10
presend_backspaces_delay: 20

The “Snippets” (match.yml)

Located in the match folder.

# 1. THE GLOBAL VARIABLE
# This is defined at the very top so EVERY shortcut can use it.
global_vars:
  - name: current_date
    type: date
    params:
      format: "%Y-%m-%d %H:%M"

# 2. THE MATCHES
matches:
  # A simple text replacement
  - trigger: "/kn"
    replace: "Kael'Nyrin "

  # A timestamp expansion
  - trigger: "/date"
    replace: "{{current_date}}"

  # A multi-line professional template using the "Pipe"
  - trigger: "/makerecs"
    replace: |
      Section 1: Findings
      Section 2: Recommendations
      [Drafting complete]

A Non-Geek’s Glossary

• GUI (Graphical User Interface): Pronounced “gooey.” This is any part of a computer program you interact with using a mouse, buttons, and menus. Most people prefer GUIs because they look like traditional apps, but they can sometimes “hide” or “break” the complex text-based logic happening in the background.
• YAML: A specific way of writing lists so a computer can read them without getting confused. It is very strict about spacing—think of it like a very fussy filing cabinet where every folder must be exactly two inches apart.
• X11 / Protocol: The “language” your computer uses to draw windows and handle your mouse movements. It’s the “behind the scenes” system that makes sure a window appears when you click an icon.
• KDE Plasma: The “look and feel” of the desktop. If X11 is the engine of the car, KDE Plasma is the dashboard, the seats, and the steering wheel.
• Backend: The “engine” under the hood. In this story, we switched the backend to “Clipboard,” which means the app “pastes” your text rather than “typing” it out key by key.
• Variables: Think of these as “placeholders.” Instead of typing the date manually, we use a variable called current_date that the computer fills in automatically with the correct time.
• Snippet / Match: A tiny piece of text (the “trigger”) that tells the computer to swap it out for a larger block of text (the “replacement”).
• KWrite / Notepad: Simple, clean text editors. Unlike Microsoft Word, these don’t add hidden formatting like bold or italics to your files, which makes them perfect for writing computer “instructions.”