Update instructions

_data/docs.yml

@@ -12,4 +12,10 @@
   desc: This section will cover the basics and the creation of espanso packages.
 - name: Configuration
   link: /docs/configuration/
-  desc: This sections will cover the configuration options and behaviour.
+  desc: This section will cover the configuration options and behaviour.
+- name: Passive Mode
+  link: /docs/passive-mode/
+  desc: An introduction to espanso's Passive Mode, one of its most powerful features.
+- name: Synchronization
+  link: /docs/sync/
+  desc: Keep espanso in sync using Dropbox, Google Drive or GitHub.

docs/configuration.md

@@ -113,7 +113,10 @@ Option | Description | Possible Values | Default | App-Specific
 --- | --- | --- | --- | ---
 `backend` | The typing engine used. `Inject` simulate keypresses, `Clipboard` simulates a copy/paste | `Clipboard` or `Inject` | `Inject` on Win and macOS, `Clipboard` on Linux | Yes
 `backspace_limit` | How many backspace espanso tracks to correct misspelled keywords | int | `3` | No
-`disabled` | Set the current configuration as disabled | `True`/`False` | `False` | Yes
+`enable_active` | Disable the active mode for the current configuration | `True`/`False` | `True` | Yes
+`enable_passive` | Disable the passive mode for the current configuration | `True`/`False` | `False` | Yes
 `parent` | The target for the current configuration file, mainly used in packages | string | `self` | Yes
 `ipc_server_port` | Windows only. Set the daemon listening port | int | `34982` | No
-`exclude_default_matches` | Used in app-specific configs, avoid parent matches | `True`/`False` | `False` | Yes
+`exclude_default_entries` | Used in app-specific configs, avoid parent matches and global variables | `True`/`False` | `False` | Yes
+`toggle_key` | Change the key used to toggle espanso active mode | `CTRL`, `ALT`, `SHIFT`, `META` | `ALT` | No
+`passive_key` | Change the key used to trigger passive mode | `CTRL`, `ALT`, `SHIFT`, `META` | `OFF` | No

docs/matches.md

@@ -119,6 +119,32 @@ the **extension** that will be executed to calculate its value. In this case, we
 
 In the remaining lines we declared the **parameters** used by the extension, in this case the *date format*.
 
+### Global Variables
+
+Introduced in version 0.5.0, *global variables* allow the definition of variables that can be used in all matches. In your `default.yml` file,
+you can add:
+
+```yaml
+global_vars:
+  - name: "global1"
+    type: "shell"
+    params:
+      cmd: "echo global var"
+  - name: "greet"
+    type: "dummy"
+    params:
+      echo: "Hey"
+```
+
+At this point, you can use `global1` and `greet` in all your matches:
+
+```yaml
+- trigger: ":hello"
+  replace: "{{greet}} Jon"
+```
+
+And typing `:hello` will result in `Hey Jon`.
+
 ### Cursor Hints
 
 Let's say you want to use espanso to expand some HTML code snippets, such as:
@@ -228,6 +254,25 @@ and store all your images there. Let's say I stored the `cat.png` image. We can
     image_path: "$CONFIG/images/cat.png"
 ```
 
+### Nested Matches
+
+Introduced in version 0.5.0, *nested matches* allow to include the output of a match inside another one.
+
+```yaml
+- trigger: ":one"
+  replace: "nested"
+
+- trigger: ":nested"
+  replace: "This is a {{output}} match"
+  vars:
+    - name: output
+      type: match
+      params:
+        trigger: ":one"
+```
+
+At this point, if you type `:nested` you'll see `This is a nested match appear`.
+
 ### Script Extension
 
 There will be tasks for which espanso was not designed for. For those cases, espanso offers the

docs/passive-mode.md

@@ -0,0 +1,174 @@
+---
+title: Passive Mode
+layout: docs
+---
+> Note: at the moment, passive mode is still experimental and has to be enabled manually. Please see the "Enabling passive mode" section below.
+
+In version 0.5.0, espanso introduced *Passive Mode*, a new feature which allows the user
+to expand matches after typing them, instead of in realtime. The feature works as follows:
+
+* Type a message containing any number of matches (passive mode matches are more limited, see the *Limitations* paragraph below)
+* Select the text you want to process (conveniently done with the CTRL+A shortcut)
+* Double press the `CTRL` key (you can customize this key).
+
+As a result, espanso will copy the text, process it expanding all the matches, and then paste it back in the field.
+
+![Passive Mode Example](/assets/images/passivemode1.gif)
+
+### Enabling passive mode
+
+Passive mode is still in its experimental stage, so it must be enabled manually. Add the following lines in the
+`default.yml` file:
+
+```yaml
+enable_passive: true
+passive_key: CTRL
+```
+
+Currently, the `passive_key` parameter accept the following alternatives: `CTRL`, `ALT`, `SHIFT` and `META` (Win key on Windows and Linux, CMD on macOS). If you'd like other possibilities, please open an issue.
+
+### Format
+
+Passive match triggers are a bit more limited than normal triggers. In particular, they have to start with a `:` prefix (though you can customize it, see below)
+and should not contain spaces.
+
+The default format of passive matches is:
+
+```
+:trigger/arg1/arg2/
+```
+
+But arguments are optional:
+
+```
+:trigger
+```
+
+> You can customize the default format by changing the configuration file, please take a look at the "Advanced Configuration" below.
+
+### Arguments
+One of the most requested features has always been *match arguments*. Due to the realtime nature
+of espanso, this problem was very difficult to solve in a solid way. The solution is to use
+passive mode, so that espanso can analyze whole sentences and execute a more complex elaboration.
+
+![argument](/assets/images/passivemode2.gif)
+
+Which can be obtained with the following:
+
+```yaml
+- trigger: ":greet"
+  replace: "Hey $0$, how are you?\nIt's been a while!"
+  passive_only: true
+```
+
+If you select `:greet/Jon/` and trigger the passive mode, the match will be expanded producing:
+
+```
+Hey Jon, how are you?
+It's been a while!
+```
+
+The `$0$` keyword indicates where the argument should be placed, and you can also pass multiple arguments, so 
+that they becomes `$1$`, `$2$`, ecc.
+
+Notice the `passive_only` keyword, which makes espanso ignore the match when typing it (otherwise, espanso would
+expand it right away).
+
+The really powerful thing is that you can **pass these arguments to the shell or custom scripts** as well:
+
+#### Integration with Shell
+
+![argumentshell](/assets/images/passivemode3.gif)
+
+This can be done by including `$0`, `$1` in the `cmd` parameter:
+
+```yaml
+- trigger: ":rev"
+  replace: "{{output}}"
+  passive_only: true
+  vars:
+    - name: output
+      type: shell
+      params:
+        cmd: "echo $0 | rev"
+        trim: true
+```
+
+**For Windows users**: instead of `$0`, you must use `%0`.
+
+#### Integration with Scripts
+
+Using the `inject_args` parameter, arguments will be appended to the given list when launching a program. For example:
+
+```yaml
+- trigger: ":pyscript"
+  replace: "{{output}}"
+  vars:
+    - name: output
+      type: script
+      params:
+        inject_args: true
+        args:
+          - python
+          - /path/to/your/script.py
+```
+
+At this point, if you expand `:pyscript/hello/`, your script will receive "hello" as the first argument.
+
+### Limitations
+
+* **Passive mode does not work in terminals**. Unfortunately, because this feature heavily uses selections
+and copy/pasting to work, I still haven't figured out a way to reliably make them work in terminals.
+
+* **Matches have to start with a specific character**. The default character is `:`, but that can be customized
+by changing the `passive_match_regex` parameter. This constraint has been added to improve the analysis efficiency.
+
+* **Passive matches do not support images**.
+
+### Advanced Customization
+
+If you don't like the `:trigger/arg1/arg2/` syntax, you can customize it by changing a few parameters in your `default.yml` config as follow:
+
+#### `passive_match_regex`
+
+With the `passive_match_regex` you can customize the main trait of the passive matches, such as the prefix character and the **external** argument separators.
+By default, it has the following value (notice the `\\` escaping which is mandatory):
+
+```yaml
+passive_match_regex: "(?P<name>:\\p{L}+)(/(?P<args>.*)/)?"
+```
+
+It may seem scary at first, but it's pretty easy to change. For example, let's say you want to start passive matches with `.` instead of `:`, you can write:
+
+```yaml
+passive_match_regex: "(?P<name>.\\p{L}+)(/(?P<args>.*)/)?"
+```
+
+Notice the `.` after `<name>` instead of the `:`.
+
+Another thing you may want to change are the external argument separators, let's say you want to use parenthesis `()` instead of the default `//`. A solution would be:
+
+```yaml
+passive_match_regex: "(?P<name>:\\p{L}+)(\\((?P<args>.*)\\))?"
+```
+
+Notice the `\\(` and `\\)` difference before and after the `<args>` cell. 
+
+A thing to keep in mind here is that, although you changed the external argument char, you 
+didn't change the **argument delimiter**, and therefore you still need to write `:trigger(arg1/arg2)`. To solve the problem, you have to change the following parameter:
+
+#### `passive_arg_delimiter`
+
+Let's say you want to separate inner arguments by a comma `,`, such as `:trigger/arg1,arg2/`. You can do so by customizing the `passive_arg_delimiter` param:
+
+```yaml
+passive_arg_delimiter: ","
+```
+
+An important thing to keep in mind here is **escaping**: what if one of the arguments contains the arg delimiter? 
+
+By default, you can escape the character with `\`,  such as `:trigger/Today is the 10\/12/`, but you can also change this escaping char by using the following parameter:
+
+#### `passive_arg_escape`
+
+This option regulates which character will act as an escape, by default is `\`.

docs/sync.md

@@ -0,0 +1,82 @@
+---
+title: Synchronization
+layout: docs
+---
+After using espanso for a while, you may need to synchronize your configuration between devices. Luckly for you, the espanso
+file-based configuration makes it pretty easy to accomplish using a Cloud Storage service (such as Dropbox, Google Drive, ecc)
+or even GitHub!
+
+> From now on, I will only mention "Dropbox folder" for brevity, but you can apply the same procedure for every service.
+
+The general idea, which applies to all operating systems, is the following:
+
+* Move the espanso configuration folder inside your Dropbox folder (also a subdirectory is perfectly file)
+* Create a **symbolic link** in the original position, pointing to the synched folder.
+
+The specific commands depend on you OS:
+
+### Windows
+
+By default, the espanso configuration folder resides in this folder (change "user" with your username):
+
+```
+C:\Users\user\AppData\Roaming\espanso
+```
+
+The first step is moving this folder in your Dropbox folder, for example in:
+
+```
+C:\Users\user\Dropbox\espanso
+```
+
+Now you need to create a **symbolic link**. Open the Command Prompt and type the following command, making sure you specify the correct paths:
+
+```
+mklink /J "C:\Users\user\AppData\Roaming\espanso" "C:\user\Freddy\Dropbox\espanso"
+```
+
+Now restart espanso and you should be ready to go!
+
+### macOS
+
+By default, the espanso configuration folder resides in this folder (change "user" with your username):
+
+```
+/Users/user/Library/Preferences/espanso
+```
+
+The first step is moving this folder in your Dropbox folder, for example in:
+
+```
+/Users/user/Dropbox/espanso
+```
+
+Now you need to create a **symbolic link**. Open the Terminal and type the following command, making sure you specify the correct paths:
+
+```
+ln -s "/Users/user/Dropbox/espanso" "/Users/user/Library/Preferences/espanso"
+```
+
+Now restart espanso and you should be ready to go!
+
+### Linux
+
+By default, the espanso configuration folder resides in this folder (change "user" with your username):
+
+```
+/home/user/.config/espanso
+```
+
+The first step is moving this folder in your Dropbox folder, for example in:
+
+```
+/home/user/Dropbox/espanso
+```
+
+Now you need to create a **symbolic link**. Open the Terminal and type the following command, making sure you specify the correct paths:
+
+```
+ln -s "/home/user/Dropbox/espanso" "/home/user/.config/espanso"
+```
+
+Now restart espanso and you should be ready to go!

install/linux.md

@@ -15,6 +15,38 @@ Currently espanso supports X11 systems only.
 
 ### Installing on Ubuntu / Debian
 
+You can install espanso in various ways on Debian-based systems. As of now, the recommended way is to use the `DEB` package method.
+
+#### Installing using DEB package
+
+Espanso ships with a `.deb` package, which makes it pretty convenient to install on Debian-based systems.
+
+Start by downloading the latest release:
+
+```
+wget https://github.com/federico-terzi/espanso/releases/latest/download/espanso-debian-amd64.deb
+```
+
+> If you want to verify the correctness of the archive, in the [Github Releases](https://github.com/federico-terzi/espanso/releases/) page you will find the **SHA256** hash in the file `espanso-debian-amd64-sha256.txt`.
+
+You can now install the package using:
+
+```
+sudo apt install ./espanso-debian-amd64.deb
+```
+
+You should now have espanso installed in your system. To start it, type the following command:
+
+```
+espanso start
+```
+
+If you now type `:espanso` in any text field, you should see "Hi there!" appear! 
+
+At this point, you are ready to read the [Getting Started](/docs/get-started/) tutorial.
+
+#### Manual installation
+
 Espanso depends upon the `X11 Record Extension`, the `xdo library`, the `xclip` command and
 the `libnotify-bin` library, so you will need to install 
 those first with the following commands: