alee/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Now with more & cleaner docs (probably).

Browse Source
This commit is contained in:
Aaron D. Lee
2025-12-14 15:27:09 -05:00
parent a2acf69a8a
commit 11e1e8d06e
4 changed files with 491 additions and 943 deletions
Download Patch File Download Diff File Expand all files Collapse all files

488
docs/ESPANSO.md
View File

@@ -1,92 +1,35 @@
# Espanso Quick Reference Guide
# Espanso Quick Reference
A comprehensive guide to using espanso text expansion with Aaron D. Lee's custom configuration.
Text expansion with 100+ pre-configured snippets using `..trigger` syntax.
> **Last Updated**: 2025-12-14
## 🚀 Getting Started
### Installation
Espanso is automatically installed when you run the main install script:
```bash
./install.sh
```
Or install it separately:
```bash
# Arch Linux
paru -S espanso-bin
espanso service register
# Ubuntu/Debian
wget https://github.com/espanso/espanso/releases/latest/download/espanso-debian-x11-amd64.deb
sudo apt install ./espanso-debian-x11-amd64.deb
espanso service register
# macOS
brew tap espanso/espanso
brew install espanso
espanso service register
```
### Initial Setup
Run the setup wizard to personalize your configuration:
```bash
cd ~/.dotfiles
./bin/setup-espanso.sh
```
This will:
- Personalize your snippets with your information
- Install optional espanso packages
- Show you useful triggers and tips
## ⌨️ Basic Controls
## Controls
| Action | Shortcut |
|--------|----------|
| Toggle espanso on/off | `ALT+SHIFT+E` |
| Open search menu | `ALT+SPACE` |
| Restart espanso | `espanso restart` |
| Check status | `espanso status` |
| Toggle on/off | `ALT+SHIFT+E` |
| Search snippets | `ALT+SPACE` |
| Restart | `espanso restart` |
| Status | `espanso status` |
## Complete Snippet Reference
## Snippet Reference
All triggers use the `..` prefix for consistency and to avoid accidental expansion.
### Date & Time
### Date & Time Stamps
| Trigger | Output |
|---------|--------|
| `..date` | 2025-12-14 |
| `..sds` | 20251214 (filename-safe) |
| `..time` | 14:30:45 |
| `..ts` | 2025-12-14T14:30:45.123Z |
| `..utc` | 2025-12-14 14:30:45.123 UTC |
| `..dt` | 2025-12-14 14:30:45 EST |
| `..epoch` | 1702573845 |
| `..epochms` | 1702573845123 |
| `..month` | December |
| `..day` | Saturday |
| `..week` | Week 50 |
| Trigger | Output | Example |
|---------|--------|---------|
| `..date` | Current date | `2025-12-14` |
| `..ds` | Date stamp (alias) | `2025-12-14` |
| `..sds` | Short date (filename safe) | `20251214` |
| `..ts` | UTC ISO 8601 timestamp | `2025-12-14T14:30:45.123Z` |
| `..time` | Current time | `14:30:45` |
| `..utime` | UTC time | `14:30:45` |
| `..ztime` | Time with timezone | `14:30:45.123 EST` |
| `..uztime` | UTC time with timezone | `14:30:45.123 UTC` |
| `..dt` | Date/time with timezone | `2025-12-14 14:30:45 EST` |
| `..udt` | UTC date/time | `2025-12-14 14:30:45 UTC` |
| `..utc` | Full UTC timestamp | `2025-12-14 14:30:45.123 UTC` |
| `..month` | Current month name | `December` |
| `..year` | Current year | `2025` |
| `..week` | Week number | `Week 50` |
| `..day` | Day of week | `Saturday` |
### Unix Timestamps
| Trigger | Output | Example |
|---------|--------|---------|
| `..epoch` | Unix timestamp (seconds) | `1702573845` |
| `..epochms` | Unix timestamp (milliseconds) | `1702573845123` |
### Git Shortcuts
### Git
| Trigger | Output |
|---------|--------|
@@ -96,12 +39,10 @@ All triggers use the `..` prefix for consistency and to avoid accidental expansi
| `..glog` | `git log --oneline --graph --decorate --all` |
| `..gpush` | `git push origin ` |
| `..gpull` | `git pull origin ` |
| `..gbranch` | `git branch -a` |
| `..gdiff` | `git diff` |
| `..gadd` | `git add .` |
| `..branch` | Current git branch name |
| `..branch` | Current branch name (dynamic) |
### Docker Shortcuts
### Docker
| Trigger | Output |
|---------|--------|
@@ -111,106 +52,34 @@ All triggers use the `..` prefix for consistency and to avoid accidental expansi
| `..dcdown` | `docker-compose down` |
| `..dlog` | `docker logs -f ` |
| `..dexec` | `docker exec -it ` |
| `..dim` | `docker images` |
| `..dprune` | `docker system prune -af` |
### System Information
### System Info
| Trigger | Output | Description |
|---------|--------|-------------|
| `..ip` | Your public IP | Via ifconfig.me |
| `..locip` | Your local IP | From hostname -i |
| Trigger | Output |
|---------|--------|
| `..ip` | Public IP (via curl) |
| `..locip` | Local IP |
### Code Templates
| Trigger | Output |
|---------|--------|
| `..bash` | Bash script template with shebang and error handling |
| `..python` | Python script template with main function |
| `..she!` | `#!/usr/bin/env bash` (shebang only) |
| `..bash` | Bash script with shebang + `set -euo pipefail` |
| `..python` | Python script with main() |
| `..she!` | `#!/usr/bin/env bash` |
**Bash Template:**
```bash
#!/usr/bin/env bash
set -euo pipefail
```
**Python Template:**
```python
#!/usr/bin/env python3
def main():
pass
if __name__ == "__main__":
main()
```
### Markdown Helpers
### Markdown
| Trigger | Output |
|---------|--------|
| `..mdcode` | Markdown code block |
| `..mdcode` | Code block |
| `..mdbash` | Bash code block |
| `..mdpy` | Python code block |
| `..mdjs` | JavaScript code block |
| `..mdtable` | Markdown table template |
| `..mdlink` | Markdown link (interactive) |
| `..mdimg` | Markdown image (interactive) |
| `..mdtable` | Table template |
| `..mdlink` | Link (prompts for text/url) |
**Table Template:**
```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell 1 | Cell 2 | Cell 3 |
```
### Emoticons & Symbols
| Trigger | Output |
|---------|--------|
| `..shrug` | ¯\\\_(ツ)_/¯ |
| `..flip` | (╯°□°)╯︵ ┻━┻ |
| `..unflip` | ┬─┬ ノ( ゜-゜ノ) |
| `..lenny` | ( ͡° ͜ʖ ͡°) |
| `..check` | ✓ |
| `..cross` | ✗ |
| `..arrow` | → |
| `..larrow` | ← |
### Quick Responses
| Trigger | Output |
|---------|--------|
| `..brb` | Be right back |
| `..omw` | On my way |
| `..tyvm` | Thank you very much |
| `..lgtm` | Looks good to me |
| `..wfm` | Works for me |
| `..ack` | Acknowledged |
| `..asap` | As soon as possible |
### File Paths & Navigation
| Trigger | Output |
|---------|--------|
| `..~` | `cd ~` |
| `..tmp` | `cd /tmp/` |
| `..logs` | `cd /var/log/` |
### Common URLs
| Trigger | Output |
|---------|--------|
| `..gh` | https://github.com |
| `..gl` | https://gitlab.com |
| `..gist` | https://gist.github.com |
| `..so` | https://stackoverflow.com |
| `..reddit` | https://reddit.com |
### Programming Comments
### Comments
| Trigger | Output |
|---------|--------|
@@ -218,68 +87,75 @@ if __name__ == "__main__":
| `..fixme` | `// FIXME: ` |
| `..note` | `// NOTE: ` |
| `..hack` | `// HACK: ` |
| `..debug` | `// DEBUG: ` |
### Common Commands
### Quick Commands
| Trigger | Output |
|---------|--------|
| `..ll` | `ls -lah` |
| `..la` | `ls -A` |
| `..grep` | `grep -rni "" .` |
| `..find` | `find . -name ""` |
| `..port` | `lsof -i :` |
| `..kill` | `kill -9 ` |
| `..proc` | `ps aux | grep ` |
| `..disk` | `df -h` |
| `..mem` | `free -h` |
### Lorem Ipsum
### Emoticons
| Trigger | Output |
|---------|--------|
| `..lorem` | Single paragraph |
| `..loremlong` | Extended lorem ipsum (4 sentences) |
| `..shrug` | ¯\\\_(ツ)\_/¯ |
| `..flip` | (╯°□°)╯︵ ┻━┻ |
| `..unflip` | ┬─┬ ノ( ゜-゜ノ) |
| `..lenny` | ( ͡° ͜ʖ ͡°) |
| `..check` | ✓ |
| `..cross` | ✗ |
| `..arrow` | → |
### Quick Responses
| Trigger | Output |
|---------|--------|
| `..brb` | Be right back |
| `..lgtm` | Looks good to me |
| `..wfm` | Works for me |
| `..tyvm` | Thank you very much |
### Auto-Corrections
These work automatically without the `..` prefix:
These work without `..` prefix:
| Typo | Correction |
|------|------------|
| `teh` | the |
| `recieve` | receive |
| `seperator` | separator |
| `definately` | definitely |
| `occured` | occurred |
| `lenght` | length |
| `wierd` | weird |
| `thier` | their |
| teh | the |
| recieve | receive |
| definately | definitely |
| seperator | separator |
| occured | occurred |
| lenght | length |
| wierd | weird |
| thier | their |
## Creating Custom Snippets
## Adding Custom Snippets
Edit your snippet files:
```bash
# Base snippets (general use)
vim ~/.config/espanso/match/base.yml
# Personal snippets (your info)
vim ~/.config/espanso/match/personal.yml
```
### Simple Text Replacement
Edit `~/.config/espanso/match/base.yml`:
```yaml
matches:
# Simple replacement
- trigger: "..hw"
replace: "Hello, World!"
```
### With Date Variables
# With shell command
- trigger: "..uptime"
replace: "{{output}}"
vars:
- name: output
type: shell
params:
cmd: 'uptime -p'
```yaml
matches:
# With date
- trigger: "..today"
replace: "Today is {{mydate}}"
vars:
@@ -289,204 +165,34 @@ matches:
format: "%B %d, %Y"
```
### With Shell Commands
After editing: `espanso restart`
## Config Locations
```yaml
matches:
- trigger: "..uptime"
replace: "{{output}}"
vars:
- name: output
type: shell
params:
cmd: 'uptime -p'
```
### Multi-line Templates
```yaml
matches:
- trigger: "..header"
replace: |
# ============================================================================
# {{title}}
# Author: Aaron D. Lee
# Date: {{date}}
# ============================================================================
vars:
- name: title
type: form
params:
layout: "Title: {{title}}"
- name: date
type: date
params:
format: "%Y-%m-%d"
~/.config/espanso/
├── config/default.yml # Settings
└── match/
├── base.yml # Main snippets
└── personal.yml # Your info
```
## Package Management
### List Installed Packages
```bash
espanso package list
```
### Install Additional Packages
```bash
# Emoji support
espanso install emoji --force
# Greek letters
espanso install greek-letters --force
# Math symbols
espanso install math --force
# Complete emoji collection
espanso install all-emojis --force
```
### Browse Available Packages
Visit: https://hub.espanso.org/
## Configuration
### Main Configuration
Location: `~/.config/espanso/config/default.yml`
Key settings:
```yaml
# Toggle key
toggle_key: ALT+SHIFT+E
# Search shortcut
search_shortcut: ALT+SPACE
# Backend
backend: Auto
# Show notifications
show_notifications: true
# Auto-restart on config changes
auto_restart: true
```
### Match Files
- `~/.config/espanso/match/base.yml` - Main snippets (100+ triggers)
- `~/.config/espanso/match/personal.yml` - Personal information
## Troubleshooting
### Espanso Not Working
```bash
espanso status # Check if running
espanso restart # Restart service
espanso log # View logs
espanso match list # List all triggers
```
1. Check if running:
```bash
espanso status
```
2. Restart the service:
```bash
espanso restart
```
3. Check logs:
```bash
espanso log
```
### Snippets Not Expanding
1. Verify the trigger syntax in your YAML files
2. Check for YAML syntax errors:
```bash
espanso match list
```
3. Ensure espanso is enabled (not toggled off with `ALT+SHIFT+E`)
### Test a Specific Trigger
## Installing Packages
```bash
# List all matches
espanso match list | grep "..date"
# Check if trigger is recognized
espanso match list | grep "trigger"
espanso install emoji # :smile: → 😊
espanso install greek-letters # :alpha: → α
espanso install math # :sum: → ∑
espanso package list # Show installed
```
## Pro Tips
1. **Consistent Naming**: All triggers use `..` prefix to avoid accidents
2. **Quick Testing**: Type trigger in any text field to test immediately
3. **Search Feature**: Use `ALT+SPACE` to search all available snippets
4. **Restart After Changes**: `espanso restart` after editing YAML files
5. **Check Logs**: Use `espanso log` to debug issues
6. **Backup Your Config**: Your espanso config is in your dotfiles repo!
## Common Workflows
### Developer Workflow
```
..gstat → Check git status
..gadd → Stage all changes
..gcm → Commit with message
..gpush → Push to remote
```
### Documentation Writing
```
..date → Add current date
..mdcode → Insert code block
..mdtable → Create table
..todo → Add TODO comment
```
### System Administration
```
..dps → Check running containers
..disk → Check disk usage
..mem → Check memory usage
..port → Check port usage
```
## Syncing Across Systems
Your espanso config is part of your dotfiles:
```bash
# On system A (after making changes)
cd ~/.dotfiles
git add espanso/
git commit -m "Update espanso snippets"
git push
# On system B (pull changes)
cd ~/.dotfiles
git pull
espanso restart
```
## Resources
- [Official Documentation](https://espanso.org/docs/)
- [Package Hub](https://hub.espanso.org/)
- [GitHub Repository](https://github.com/espanso/espanso)
- [Community Forum](https://github.com/espanso/espanso/discussions)
---
**Configuration Location**: `~/.config/espanso/`
**Total Triggers**: 100+ pre-configured
**Custom Prefix**: `..` (double period)
**Last Updated**: 2025-12-14
Add your own snippets to `personal.yml` for custom shortcuts!
Browse more: https://hub.espanso.org/