diff --git a/docs/cheatsheet/README.md b/docs/cheatsheet/README.md
index b6c5fc5..1e44720 100644
--- a/docs/cheatsheet/README.md
+++ b/docs/cheatsheet/README.md
@@ -4,7 +4,7 @@
* [Navi cheatsheets](#navi-cheatsheets)
* [Working with `cheatsheet repositories`](#working-with-cheatsheet-repositories)
* [Manually adding cheatsheets to navi](#manually-adding-cheatsheets-to-navi)
- * [Submitting cheatsheets](#submitting-cheatsheets)
+ * [Choosing between queries and selection with variables](#choosing-between-queries-and-selection-with-variables)
* [Using cheatsheets from other tools](#using-cheatsheets-from-other-tools)
@@ -32,6 +32,17 @@ but a quick working command to go there would be:
cd $(navi info default-cheats-path)
```
+## Choosing between queries and selection with variables
+
+Navi lets you use different methods to fill a variable value, when prompted.
+
+| Keyboard key | Preference |
+|:------------------:|:--------------------------:|
+| tab | The query is preferred |
+| enter | The selection is preferred |
+
+It means if you enter the tab key, navi will let you enter the value.
+
## Using cheatsheets from other tools
> [!WARNING]
diff --git a/docs/cheatsheet/syntax/README.md b/docs/cheatsheet/syntax/README.md
index 531b411..375cfb6 100644
--- a/docs/cheatsheet/syntax/README.md
+++ b/docs/cheatsheet/syntax/README.md
@@ -1,17 +1,10 @@
# The syntax of a Navi cheatsheet
-- [Syntax overview](#syntax-overview)
-- [Folder structure](#folder-structure)
-- [Variables](#variables)
-- [Advanced variable options](#advanced-variable-options)
-- [Variable dependency](#variable-dependency)
-- [Multiline snippets](#multiline-snippets)
-- [Variable as multiple arguments](#variable-as-multiple-arguments)
-- [Aliases](#aliases)
-### Syntax overview
+## Syntax overview
-Cheatsheets are described in `.cheat` (or `.cheat.md`) files that look like this:
+Cheats are described in cheatsheet files.\
+A cheatsheet is a file that has a `.cheat` or `.cheat.md` extension and looks like this:
```sh
% git, code
@@ -22,80 +15,89 @@ git checkout
$ branch: git branch | awk '{print $NF}'
```
-Lines starting with:
+A cheatsheet can have the following elements:
-- `%`: determine the start of a new cheatsheet and should contain tags
-- `#`: should be descriptions of commands
-- `;`: are ignored. You can use them for metacomments
-- `$`: should contain commands that generate a list of possible values for a given argument [:information_source:](#variables)
-- `@`: should contain tags whose associated cheatsheet you want to base on [:information_source:](#extending-cheatsheets)
-
-All the other non-empty lines are considered as executable commands.
+| Element | Syntax | Description |
+|:--------------------------------:|:------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
+| Tags as cheat titles | `%` | Lines starting with this character are considered the start of a new cheat command and should contain tags. |
+| Cheat Description | `#` | Lines starting with this character should be the description of the cheat you're writing. |
+| Cheat Comments (or Metacomments) | `;` | Lines starting with this character will be ignored by navi but they can be great as editor's comments. |
+| Pre-defined variables | `$` | Lines starting with this character should contain commands that generate a list of possible values,
:information_source: See [#variables](#variables) for more details. |
+| Extended cheatS | `@` | Lines starting with this character should contain tags associated to other defined cheats.
:information_source: See [#extending-cheats](#extending-cheats) for more details. |
+| Executable commands | N/A | All other non-empty lines are considered as executable commands. |
> [!TIP]
> If you are editing cheatsheets in Visual Studio Code, you could enable syntax highlighting
> by installing this extension: [@yanivmo/navi-cheatsheet-language](https://marketplace.visualstudio.com/items?itemName=yanivmo.navi-cheatsheet-language).
-You can place commands in code blocks fenced with triple backticks (```` ``` ````).
-
-````sh
-% git, code
-
-# Change branch
-```sh
-git checkout
-```
-
-$ branch: git branch | awk '{print $NF}'
-````
-
-### Variables
-
-The interface prompts for variable names inside brackets (eg ``).
+## Variables
+Variables are defined with brackets inside executable commands (e.g. ``).\
Variable names should only include alphanumeric characters and `_`.
-If there's a corresponding line starting with `$` for a variable, suggestions will be displayed. Otherwise, the user will be able to type any value for it.
-
-If you hit `` the query typed will be preferred. If you hit `` the selection will be preferred.
+You can show suggestions by using the Pre-defined variables lines (i.e. lines starting with`$`).\
+Otherwise, the user will be able to type any value for it.
### Advanced variable options
-For lines starting with `$` you can use `---` to customize the behavior of `fzf` or how the value is going to be used:
+For Pre-Defined variables lines, you can use `---` to customize the behavior of `fzf`
+or how the value is going to be used.
-```sh
-# This will pick the 3rd column and use the first line as header
-docker rmi
+Below are examples of such customization:
-# Even though "false/true" is displayed, this will print "0/1"
-echo
+- We define what column to use, the number of header lines and a delimiter between values.
+
+ ```sh
+ # This will pick the 3rd column and use the first line as header
+ docker rmi
+
+ $ image_id: docker images --- --column 3 --header-lines 1 --delimiter '\s\s+'
+ ```
+
+- We modify the output values of a command
+
+ ```shell
+ # Even though "false/true" is displayed, this will print "0/1"
+ echo
+
+ $ mapped: echo 'false true' | tr ' ' '\n' --- --map "grep -q t && echo 1 || echo 0"
+ ```
-$ image_id: docker images --- --column 3 --header-lines 1 --delimiter '\s\s+'
-$ mapped: echo 'false true' | tr ' ' '\n' --- --map "grep -q t && echo 1 || echo 0"
-```
The supported parameters are:
-- `--column `: extracts a single column from the selected result
-- `--map `: _(experimental)_ applies a map function to the selected variable value
-- `--prevent-extra`: _(experimental)_ limits the user to select one of the suggestions
-- `--fzf-overrides `: _(experimental)_ applies arbitrary `fzf` overrides
-- `--expand`: _(experimental)_ converts each line into a separate argument
+| Parameter | Description |
+|:------------------------|:-----------------------------------------------------------------------------------------:|
+| `--column ` | `` is the column number to extract from the result. |
+| `--map ` | **_[EXPERIMENTAL]_** `` is a map function to apply to the variable value. |
+| `--prevent-extra` | **_[EXPERIMENTAL]_** This parameter will limit the user to select one of the suggestions. |
+| `--fzf-overrides ` | **_[EXPERIMENTAL]_** `` is an arbitrary argument to override `fzf` behaviour. |
+| `--expand` | **_[EXPERIMENTAL]_** This parameter will convert each line into a separate argument. |
+
In addition, it's possible to forward the following parameters to `fzf`:
-- `--multi`
-- `--header-lines `
-- `--delimiter `
-- `--query `
-- `--filter `
-- `--header `
-- `--preview `
-- `--preview-window `
+| Parameter forwarded to `fzf` |
+|:----------------------------:|
+| `--multi` |
+| `--header-lines ` |
+| `--delimiter ` |
+| `--query ` |
+| `--filter ` |
+| `--header ` |
+| `--preview ` |
+| `--preview-window ` |
### Variable dependency
-The command for generating possible inputs can implicitly refer other variables by using the `` syntax:
+Pre-Defined variables can refer other defined variables in two different ways, an implicit and explicit way.
+
+#### Implicit dependencies
+
+An implicit dependency is when you refer another variable with the same syntax used in
+executable commands (i.e. ``).
+
+The example below shows how we can depend on multiple variables to construct a path:
```sh
# Should print /my/pictures/wallpapers
@@ -105,7 +107,11 @@ $ pictures_folder: echo "/my/pictures"
$ wallpaper_folder: echo "/wallpapers"
```
-If you want to make dependencies explicit, you can use the `$varname` syntax:
+#### Explicit dependencies
+
+An explicit dependency is when you prepend a dollar sign (i.e. `$`) to the variable name.
+
+Below is an example of using explicit dependencies to give multiple choices:
```sh
# If you select "hello" for , the possible values of will be "hello foo" and "hello bar"
@@ -118,9 +124,23 @@ $ x: echo "hello hi" | tr ' ' '\n'
$ y: echo "$x foo;$x bar" | tr ';' '\n'
```
-### Extending cheatsheets
+### Variable as multiple arguments
-With the `@ same tags from other cheatsheet` syntax you can reuse the same variable in multiple cheatsheets.
+Variables can have multiple arguments,
+below is an example of using multiple arguments to cat multiple files at the same time.
+
+```sh
+# This will result into: cat "file1.json" "file2.json"
+cat
+
+$ jsons: find . -iname '*.json' -type f -print --- --multi --expand
+```
+
+## Extending cheats
+
+Navi allows you to extend a cheat context with `Extended cheats` lines (i.e. starting with `@`).\
+If you put the same tags from another cheat, you will be able to share the same context and will
+be able to use the same variables, for example.
```sh
% dirs, common
@@ -140,31 +160,45 @@ echo "/wallpapers"
echo "/screenshots"
```
-### Multiline snippets
+## Multiline commands/snippets
-Commands may be multiline:
+Commands can be multiline, we call them snippets.
-```sh
-# This will output "foo\nyes"
-echo foo
-true \
- && echo yes \
- || echo no
-```
+- You can write them as follows:
-### Variable as multiple arguments
+ ```sh
+ % bash, foo
-```sh
-# This will result into: cat "file1.json" "file2.json"
-cat
+ # This will output "foo\nyes"
+ echo foo
+ true \
+ && echo yes \
+ || echo no
+ ```
-$ jsons: find . -iname '*.json' -type f -print --- --multi --expand
-```
-### Aliases
+- Or, you can place them inside Markdown code blocks, delimited by triple backticks (```` ``` ````):
-**navi** doesn't have support for aliases as first-class citizens at the moment.
+ ````sh
+ % git, code
+
+ # Change branch
+ ```sh
+ git checkout
+ ```
+
+ $ branch: git branch | awk '{print $NF}'
+ ````
-However, it is trivial to create aliases using **navi** + a few conventions.
+
+## Aliases
+
+**navi** doesn't have support for aliases as first-class citizens at the moment.\
+However, it is easy to create aliases using **navi** + a few conventions.
+
+> [!CAUTION]
+> The examples below will only work if you use **navi** as a shell scripting tool.
+>
+> See [/docs/usage/shell-scripting](/docs/usage/shell-scripting/README.md) for more details.
For example, suppose you decide to end some of your commands with `:: `:
@@ -178,7 +212,7 @@ echo lorem ipsum
echo foo bar
```
-Then, if you use **navi** as a [shell scripting tool](shell_scripting.md), you could add something similar to this in your `.bashrc`-like file:
+You could add something similar to this in your `.bashrc`-like file:
```bash
navialias() {