diff --git a/docs/configuration.md b/docs/configuration.md index 60b68c0..5c71b55 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -41,6 +41,65 @@ This location is now deprecated and, while being still supported for compatibili * Copy the contents of the `packages` folder into the new `packages` path ( you can find the new package location with the `espanso path` command ). +### Quick Editing + +Introduced in version 0.5.1, espanso now ships with the `edit` subcommand, which makes editing configuration files much more convenient. Let's see how it works: + +If you open a terminal and type: + +``` +espanso edit +``` + +the default system editor (Notepad on Windows and Nano on Unix systems) will be spawned, editing the `default.yml`. +Then, after you saved the file and exited the editor, **espanso will automatically restart, loading the new changes**. + +#### Customizing the editor + +If you want to use another editor, customizing it is super easy, just specify your choice in the `EDITOR` (or `VISUAL`) +envorionment variables, such as: + +``` +EDITOR=/usr/bin/vim +``` + +#### Editing files in the user/ directory + +If you invoke `espanso edit` without further arguments, it will open the `default.yml` file. But what if you want to edit +files in the `user/*` directory? Luckily, you can simply specify the name as an additional argument (without the extension). + +For example, if you want to edit the `user/emails.yml` file, you can type: + +``` +espanso edit emails +``` + +Note that the last command also allows the user to create a new file in the `user/` directory if it doesn't already exist. + +### Organizing Matches + +After creating a lot of matches, you may wonder if there's a way to keep them organized in multiple files instead of creating a long list in the `default.yml` configuration. +Luckily, you can split your matches into multiple files by placing them in the `user/` folder! + +Let's say you want to create a file for your email signatures. Create the `user/emails.yml` file with the following content: + +```yml +name: emails +parent: default + +matches: + - trigger: ":sig" + replace: | + Best regards, + Jon Snow +``` + +After restarting espanso (by using the `espanso restart` command), you can now use the `:sig` trigger as you would have done by inserting it into the `default.yml` configuration. + +This is made possible by the `parent: default` instruction, which tells espanso to merge the current matches into the default configuration. + +You can create as many files as you want, and keep all your matches well organized :) + ### Application-Specific Configurations Sometimes you may need to make espanso behave **differently** with some applications. For example, you may want to have diff --git a/docs/get-started.md b/docs/get-started.md index a9edab3..354a5b6 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -131,6 +131,8 @@ espanso restart Now try to type `:br` anywhere. If you did everything correctly, you should see `Best Regards` appear! +> In version 0.5.1, espanso introduced the `edit` subcommand which makes editing configuration files much easier. Take a look at [Quick Editing](/docs/configuration/#quick-editing) if you are interested. + ### Understanding Packages Custom matches are amazing, but sometimes it can be tedious to define Matches for every **common operation**, diff --git a/docs/matches.md b/docs/matches.md index f4375f9..aa6671d 100644 --- a/docs/matches.md +++ b/docs/matches.md @@ -436,4 +436,27 @@ You can use this feature by declaring a variable of type `random` and then passi ``` {% endraw %} -In this case, typing `:quote` will expand randomly to one of the tree quotes. \ No newline at end of file +In this case, typing `:quote` will expand randomly to one of the tree quotes. + +### Clipboard Extension + +Introduced in version 0.5.1, the **Clipboard Extension** now allows to include the current clipboard content in a match, which can be useful in many situations. + +For example, let's imagine you want to create the ultimate HTML link shortcut: + +{% raw %} +```yaml + - trigger: ":a" + replace: "$|$" + vars: + - name: "clipboard" + type: "clipboard" +``` +{% endraw %} + +If you now copy a link in the clipboard (for example by selecting it and then CTRL+C) and then type `:a`, you'll +see the following replacement appear: + +``` + +``` \ No newline at end of file