Merge pull request #990 from astr0n0mer/master

docs: fixes broken links

.github/CODEOWNERS

@@ -1 +1,8 @@
+# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
 * @denisidoro
+.github/* @denisidoro
+
+shell/navi.plugin.ps1 @alexis-opolka
+docs/* @alexis-opolka
+docs/**/* @alexis-opolka

.github/workflows/cd.yml

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - "*"
+  release:
 
 jobs:
   binary:
@@ -30,23 +31,42 @@ jobs:
           - os: macos-latest
             target: aarch64-apple-darwin
     steps:
-      - uses: hecrj/setup-rust-action@v1.3.4
-        with:
-          rust-version: stable
-      - uses: actions/checkout@v1
-      - name: Install target
-        id: installtarget
-        run: rustup target add ${{ matrix.target }}
-      - name: Build
-        id: build
-        run: scripts/dot rust release ${{ matrix.target }}
+      ### We're checking out the repository at the triggered ref
+      - uses: actions/checkout@v4
+
       - name: Get the version
         id: get_version
-        run: echo ::set-output name=VERSION::${GITHUB_REF/refs\/tags\//}
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Check if release exists
+        id: check_release
+        run: |
+          if gh release view ${{ steps.get_version.outputs.VERSION }} > /dev/null 2>&1; then
+            echo "RELEASE_EXISTS=true" >> $GITHUB_OUTPUT
+          else
+            echo "RELEASE_EXISTS=false" >> $GITHUB_OUTPUT
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create release
+        continue-on-error: true
+        if: steps.check_release.outputs.RELEASE_EXISTS == 'false'
+        run: |
+          gh release create ${{ steps.get_version.outputs.VERSION }} \
+            --title "Release ${{ steps.get_version.outputs.VERSION }}" \
+            --notes "Release notes for ${{ steps.get_version.outputs.VERSION }}" \
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build
+        id: build
+        run: scripts/release ${{ matrix.target }}
+
       - name: Upload binaries to release
-        uses: svenstaro/upload-release-action@v1-release
-        with:
-          repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: target/tar/navi.${{ steps.build.outputs.EXTENSION }}
-          tag: ${{ github.ref }}
-          asset_name: navi-${{ steps.get_version.outputs.VERSION }}-${{ matrix.target }}.${{ steps.build.outputs.EXTENSION }}
+        run: |
+          cd ./target/${{ matrix.target }}/release/
+          cp navi.${{ steps.build.outputs.EXTENSION }} navi-${{ steps.get_version.outputs.VERSION }}-${{ matrix.target }}.${{ steps.build.outputs.EXTENSION }}
+          gh release upload ${{ steps.get_version.outputs.VERSION }} navi-${{ steps.get_version.outputs.VERSION }}-${{ matrix.target }}.${{ steps.build.outputs.EXTENSION }}
+        env:
+          GH_TOKEN: ${{ github.token }}

.github/workflows/ci.yml

@@ -4,7 +4,10 @@
 # for simplicity we are compiling and testing everything on the Ubuntu environment only.
 # For multi-OS testing see the `cross.yml` workflow.
 
-on: [push]
+on:
+  push:
+  pull_request:
+    branches: [master]
 
 name: CI
 

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "navi"
-version = "2.23.0"
-authors = ["Denis Isidoro <denis_isidoro@live.com>"]
+version = "2.25.0-beta1"
+authors = ["Denis Isidoro <denis_isidoro@live.com>", "Alexis Opolka <alexis.opolka@protonmail.com>"]
 edition = "2021"
 description = "An interactive cheatsheet tool for the command-line"
 homepage = "https://github.com/denisidoro/navi"
@@ -24,24 +24,21 @@ regex = { version = "1.7.3", default-features = false, features = [
    "unicode-perl",
 ] }
 clap = { version = "4.2.1", features = ["derive", "cargo"] }
-crossterm = "0.26.1"
+crossterm = "0.28.0"
 lazy_static = "1.4.0"
-etcetera = "0.7.1"
+etcetera = "0.10.0"
 walkdir = "2.3.3"
 shellwords = "1.1.0"
 anyhow = "1.0.70"
-thiserror = "1.0.40"
-strip-ansi-escapes = "0.1.1"
+thiserror = "2.0.0"
+strip-ansi-escapes = "0.2.0"
 edit = "0.1.4"
-remove_dir_all = "0.8.2"
-serde = { version = "1.0.159", features = ["derive"] }
+remove_dir_all = "1.0.0"
+serde = { version = "1.0.219", features = ["derive"] }
 serde_yaml = "0.9.21"
-dns_common_derive = { version = "0.2.1" }
-dns_common = { version = "0.2.1", default-features = false, features = [
-   "yaml",
-   "json",
-] }
-unicode-width = "0.1.10"
+unicode-width = "0.2.0"
+tracing = "0.1.41"
+tracing-subscriber = { version = "0.3.19", features = ["env-filter"] }
 
 [target.'cfg(windows)'.dependencies]
 dunce = "1"

README.md

@@ -13,7 +13,7 @@ An interactive cheatsheet tool for the command-line.
 - it will make you type less
 - it will teach you new one-liners
 
-It uses [fzf](https://github.com/junegunn/fzf), [skim](https://github.com/lotabout/skim), or [Alfred](https://www.alfredapp.com/) under the hood and it can be either used as a command or as a shell widget (_à la_ Ctrl-R).
+It uses [fzf](https://github.com/junegunn/fzf) or [skim](https://github.com/lotabout/skim) under the hood and it can be either used as a command or as a shell widget (_à la_ Ctrl-R).
 
 ## Table of contents
 
@@ -23,23 +23,21 @@ It uses [fzf](https://github.com/junegunn/fzf), [skim](https://github.com/lotabo
 - [Cheatsheet syntax](#cheatsheet-syntax)
 - [Customization](#customization)
 - [More info](#more-info)
-- [Trying out online](#trying-out-online)
-- [Similar tools](#similar-tools)
-- [Etymology](#etymology)
 
 ## Installation
 
-**navi** can be installed with the following package managers:
-
-[![Packaging status](https://repology.org/badge/vertical-allrepos/navi.svg)](https://repology.org/project/navi/versions)
-
 The recommended way to install **navi** is by running:
 
 ```sh
 brew install navi
 ```
 
-If `brew` isn't available, you can check [alternative install instructions](docs/installation.md).
+> [!NOTE]
+> For more details on how to install Navi, see [docs/installation](docs/installation/README.md)
+
+**navi** can be installed with the following package managers:
+
+[![Packaging status](https://repology.org/badge/vertical-allrepos/navi.svg)](https://repology.org/project/navi/versions)
 
 ## Usage
 
@@ -47,28 +45,27 @@ There are multiple ways to use **navi**:
 
 - by typing `navi` in the terminal
   - pros: you have access to all possible subcommands and flags
-- as a [shell widget](docs/installation.md#installing-the-shell-widget) for the terminal
+- as a [shell widget](docs/widgets/README.md#installing-the-shell-widget) for the terminal
   - pros: the shell history is correctly populated (i.e. with the actual command you ran instead of `navi`) and you can edit the command as you wish before executing it
-- as a [Tmux widget](docs/tmux.md)
+- as a [Tmux widget](docs/widgets/howto/TMUX.md)
   - pros: you can use your cheatsheets in any command-line app even in SSH sessions
-- as [aliases](docs/aliases.md)
-- as a [shell scripting tool](docs/shell_scripting.md)
-- as an [Alfred workflow](docs/alfred.md)
+- as [aliases](docs/cheatsheet/syntax/README.md#aliases)
+- as a [shell scripting tool](docs/usage/shell-scripting/README.md)
 
 In particular, check [these instructions](https://github.com/denisidoro/navi/issues/491) if you want to replicate what's shown in the demo above.
 
 ## Cheatsheet repositories
 
-Running **navi** for the first time will help you download and manage cheatsheets. By default, they are soted at `~/.local/share/navi/cheats/`.
+Running **navi** for the first time will help you download and manage cheatsheets. By default, they are stored at `~/.local/share/navi/cheats/`.
 
 You can also:
 
-- [browse through featured cheatsheets](docs/cheatsheet_repositories.md#browsing-through-cheatsheet-repositories)
-- [import cheatsheets from git repositories](docs/cheatsheet_repositories.md#importing-cheatsheets)
-- [write your own cheatsheets](#cheatsheet-syntax) (and [share them](docs/cheatsheet_repositories.md#submitting-cheatsheets), if you want)
-- [use cheatsheets from other tools](docs/cheatsheet_repositories.md#using-cheatsheets-from-other-tools), such as [tldr](https://github.com/tldr-pages/tldr) and [cheat.sh](https://github.com/chubin/cheat.sh)
-- [auto-update repositories](docs/cheatsheet_repositories.md#auto-updating-repositories)
-- auto-export cheatsheets from your [TiddlyWiki](https://tiddlywiki.com/) notes using a [TiddlyWiki plugin](https://bimlas.gitlab.io/tw5-navi-cheatsheet/)
+- [browse through featured cheatsheets](docs/usage/commands/repo/README.md#browsing-through-cheatsheet-repositories)
+- [import cheatsheets from git repositories](docs/cheatsheet/repositories/README.md#importing-cheatsheet-repositories)
+- [write your own cheatsheets](#cheatsheet-syntax) (and [share them](docs/cheatsheet/repositories/README.md#submitting-cheatsheets), if you want)
+- [use cheatsheets from other tools](docs/cheatsheet/README.md#using-cheatsheets-from-other-tools), such as [tldr](https://github.com/tldr-pages/tldr) and [cheat.sh](https://github.com/chubin/cheat.sh)
+- [auto-update repositories](docs/cheatsheet/repositories/README.md#auto-updating-repositories)
+- auto-export cheatsheets from your [TiddlyWiki](https://tiddlywiki.com/) notes using a [TiddlyWiki plugin](https://bimlas.github.io/tw5-navi-cheatsheet/)
 
 ## Cheatsheet syntax
 
@@ -83,17 +80,17 @@ git checkout <branch>
 $ branch: git branch | awk '{print $NF}'
 ```
 
-The full syntax and examples can be found [here](docs/cheatsheet_syntax.md).
+The full syntax and examples can be found [here](docs/cheatsheet/syntax/README.md).
 
 ## Customization
 
 You can:
 
-- [setup your own config file](docs/config_file.md)
-- [set custom paths for your config file and cheat sheets](docs/paths_and_env_vars.md)
-- [change colors](docs/customization.md#changing-colors)
-- [resize columns](docs/customization.md#resizing-columns)
-- [change how search is performed](docs/customization.md#overriding-fzf-options)
+- [setup your own config file](docs/configuration/README.md)
+- [set custom paths for your config file and cheat sheets](docs/configuration/README.md#paths-and-environment-variables)
+- [change colors](docs/configuration/README.md#changing-colors)
+- [resize columns](docs/configuration/README.md#resizing-columns)
+- [change how search is performed](docs/configuration/README.md#overriding-fzf-options)
 
 ## More info
 
@@ -103,17 +100,4 @@ Please run the following command to read more about all possible options:
 navi --help
 ```
 
-In addition, please check the [/docs](docs) folder.
-
-## Similar tools
-
-There are many similar projects out there ([beavr](https://github.com/denisidoro/beavr), [bro](https://github.com/hubsmoke/bro), [cheat](https://github.com/cheat/cheat), [cheat.sh](https://github.com/chubin/cheat.sh), [cmdmenu](https://github.com/amacfie/cmdmenu), [eg](https://github.com/srsudar/eg), [how2](https://github.com/santinic/how2), [howdoi](https://github.com/gleitz/howdoi), [Command Line Interface Pages](https://github.com/command-line-interface-pages) and [tldr](https://github.com/tldr-pages/tldr), to name a few).
-
-They are excellent projects, but **navi** remains unique in the following ways:
-
-- it's natural to write cheatsheets tailored to your needs
-- arguments are neither hardcoded nor a simple template
-
-## Etymology
-
-[Navi](https://zelda.gamepedia.com/Navi) is a character from [The Legend of Zelda Ocarina of Time](https://zelda.gamepedia.com/Ocarina_of_Time) that provides [Link](https://zelda.gamepedia.com/Link) with a variety of clues to help him solve puzzles and make progress in his quest.
+In addition, please check the [/docs](docs) folder or the website.

docs/README.md

@@ -0,0 +1,41 @@
+# Navi <img src="https://raw.githubusercontent.com/denisidoro/navi/master/assets/icon.png" alt="icon" height="28px"/> [![Actions Status](https://github.com/denisidoro/navi/workflows/CI/badge.svg)](https://github.com/denisidoro/navi/actions) ![GitHub release](https://img.shields.io/github/v/release/denisidoro/navi?include_prereleases)
+
+## Table of Contents
+
+<!-- TOC -->
+* [Navi <img src="https://raw.githubusercontent.com/denisidoro/navi/master/assets/icon.png" alt="icon" height="28px"/> ![Actions Status](https://github.com/denisidoro/navi/workflows/CI/badge.svg) ![GitHub release](https://img.shields.io/github/v/release/denisidoro/navi?include_prereleases)](#navi-img-srchttpsrawgithubusercontentcomdenisidoronavimasterassetsiconpng-alticon-height28px--)
+  * [Table of Contents](#table-of-contents)
+  * [About](#about)
+  * [Navi Pros](#navi-pros)
+  * [Similar tools](#similar-tools)
+  * [Etymology](#etymology)
+<!-- TOC -->
+
+## About
+
+Navi is an interactive cheatsheet tool for the command-line.\
+It allows you to browse through cheatsheets (that you may write yourself or download from maintainers) and execute commands.
+
+[![Demo](https://asciinema.org/a/406461.svg)](https://asciinema.org/a/406461)
+
+It uses [fzf](https://github.com/junegunn/fzf), [skim](https://github.com/lotabout/skim), or [Alfred](https://www.alfredapp.com/) under the hood and it can be either used as a command or as a shell widget (_à la_ Ctrl-R).
+
+## Navi Pros
+
+- it will spare you from knowing CLIs by heart
+- it will spare you from copy-pasting output from intermediate commands
+- it will make you type less
+- it will teach you new one-liners
+
+## Similar tools
+
+There are many similar projects out there ([beavr](https://github.com/denisidoro/beavr), [bro](https://github.com/hubsmoke/bro), [cheat](https://github.com/cheat/cheat), [cheat.sh](https://github.com/chubin/cheat.sh), [cmdmenu](https://github.com/amacfie/cmdmenu), [eg](https://github.com/srsudar/eg), [how2](https://github.com/santinic/how2), [howdoi](https://github.com/gleitz/howdoi), [Command Line Interface Pages](https://github.com/command-line-interface-pages) and [tldr](https://github.com/tldr-pages/tldr), to name a few).
+
+They are excellent projects, but **navi** remains unique in the following ways:
+
+- it's natural to write cheatsheets tailored to your needs
+- arguments are neither hardcoded nor a simple template
+
+## Etymology
+
+[Navi](https://zelda.gamepedia.com/Navi) is a character from [The Legend of Zelda Ocarina of Time](https://zelda.gamepedia.com/Ocarina_of_Time) that provides [Link](https://zelda.gamepedia.com/Link) with a variety of clues to help him solve puzzles and make progress in his quest.

docs/cheatsheet/README.md

@@ -0,0 +1,64 @@
+# Navi cheatsheets
+
+<!-- TOC -->
+* [Navi cheatsheets](#navi-cheatsheets)
+  * [Working with `cheatsheet repositories`](#working-with-cheatsheet-repositories)
+  * [Manually adding cheatsheets to navi](#manually-adding-cheatsheets-to-navi)
+  * [Choosing between queries and selection with variables](#choosing-between-queries-and-selection-with-variables)
+  * [Using cheatsheets from other tools](#using-cheatsheets-from-other-tools)
+<!-- TOC -->
+
+## Working with `cheatsheet repositories`
+
+Navi works best with what we call `cheatsheet repositories`, for more details see [cheatsheet/repositories](repositories/README.md).
+
+## Manually adding cheatsheets to navi
+
+If you don't want to work with `cheatsheet repositories`, you can manually add your
+cheatsheets to navi by putting them into the `cheats_path` of your platform.
+
+You can find out your path using the [info](/docs/usage/commands/info/README.md) subcommands
+but a quick working command to go there would be:
+
+- Before 2.25.0
+
+    ```bash
+    cd $(navi info cheats-path)
+    ```
+
+- After 2.25.0
+
+    ```bash
+    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         |
+|:------------------:|:--------------------------:|
+|  <kbd> tab </kbd>  |   The query is preferred   |
+| <kbd> enter </kbd> | The selection is preferred |
+
+It means if you enter the <kbd> tab </kbd> key, navi will let you enter the value.
+
+## Using cheatsheets from other tools
+
+> [!WARNING]
+> Navi **DOESN'T SUPPORT** as of now importing cheatsheets from other tools
+> but is able to **work with** TLDR and Cheat.sh.
+
+![Demo](https://user-images.githubusercontent.com/3226564/91878474-bae27500-ec55-11ea-8b19-17876178e887.gif)
+
+You can use cheatsheets from [tldr](https://github.com/tldr-pages/tldr) by running:
+
+```sh
+navi --tldr <query>
+```
+
+You can use cheatsheets from [cheat.sh](https://github.com/chubin/cheat.sh) by running:
+
+```sh
+navi --cheatsh <query>
+```

docs/cheatsheet/getting-started/README.md

@@ -0,0 +1 @@
+# Cheatsheets - Getting started

docs/cheatsheet/repositories/README.md

@@ -0,0 +1,63 @@
+# Cheatsheet repositories
+
+<!-- TOC -->
+* [Cheatsheet repositories](#cheatsheet-repositories)
+  * [About](#about)
+  * [Importing cheatsheet repositories](#importing-cheatsheet-repositories)
+  * [Submitting cheatsheets](#submitting-cheatsheets)
+  * [Auto-updating repositories](#auto-updating-repositories)
+<!-- TOC -->
+
+## About
+
+Navi lets you work with what we call `cheatsheet repositories`, they are git repositories
+and mainly consists of `.cheat` files.
+
+This page is dedicated to the information you might need to work with `cheatsheet repositories`.
+
+## Importing cheatsheet repositories
+
+You can import `cheatsheet repositories` with the `repo add` subcommand.\
+See [/docs/usage/commands/repo](/docs/usage/commands/repo/README.md#importing-cheatsheet-repositories) for more details.
+
+## Submitting cheatsheets
+
+The featured repository for cheatsheets is [denisidoro/cheats](https://github.com/denisidoro/cheats),
+feel free to open a PR[^1] there for me to include your contributions.
+
+In order to add your own repository as a featured cheatsheet repo, please [edit this file](https://github.com/denisidoro/cheats/edit/master/featured_repos.txt) and open a PR[^1].
+
+## Auto-updating repositories
+
+Right now, **navi** doesn't have support for auto-updating out of the box.
+However, you can achieve this by using `git` and `crontab`.
+
+- First make sure you cloned your repo using `git` to the correct folder:
+
+  ```sh
+  user="<user>"
+  repo="<repo>"
+  git clone "https://github.com/${user}/${repo}" "$(navi info cheats-path)/${user}__${repo}"
+  ```
+
+- Then, add a cron job:
+
+  ```sh
+  crontab -e
+  */0 11 * * * bash -c 'cd "$(/usr/local/bin/navi info cheats-path)/<user>__<repo>" && /usr/local/bin/git pull -q origin master'
+  ```
+
+> [!NOTE]
+> Please note the cron job above is just an example **AND** you should edit it accordingly:
+>
+>- In this example, the cron job is triggered every day at 11am.
+>  
+>    You might want to check out [crontab guru](https://crontab.guru/) regarding crontab.
+>
+>- The full paths to `navi` and `git` may differ in your setup.
+>
+>    Check their actual values using `which` as `which <program>`.
+>
+>- Don't forget to replace `<user>__<repo>` with the actual folder name
+
+[^1]: A *PR* is short for Pull Request

docs/cheatsheet/syntax/README.md

@@ -0,0 +1,248 @@
+# The syntax of a Navi cheatsheet
+
+<!-- TOC -->
+* [The syntax of a Navi cheatsheet](#the-syntax-of-a-navi-cheatsheet)
+  * [Syntax overview](#syntax-overview)
+  * [Variables](#variables)
+    * [Advanced variable options](#advanced-variable-options)
+    * [Variable dependency](#variable-dependency)
+      * [Implicit dependencies](#implicit-dependencies)
+      * [Explicit dependencies](#explicit-dependencies)
+    * [Variable as multiple arguments](#variable-as-multiple-arguments)
+  * [Extending cheats](#extending-cheats)
+  * [Multiline commands/snippets](#multiline-commandssnippets)
+  * [Aliases](#aliases)
+<!-- TOC -->
+
+## Syntax overview
+
+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
+
+# Change branch
+git checkout <branch>
+
+$ branch: git branch | awk '{print $NF}'
+```
+
+A cheatsheet can have the following elements:
+
+|             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. <br/> <br/> :information_source: See [#variables](#variables) for more details.    |
+|         Extended cheats          |  `@`   | Lines starting with this character should contain tags associated to other defined cheats. <br/> <br/> :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).
+
+## Variables
+
+Variables are defined with brackets inside executable commands (e.g. `<branch>`).\
+Variable names should only include alphanumeric characters and `_`.
+
+You can show suggestions by using the Pre-defined variable lines (i.e. lines starting with`$`).\
+Otherwise, the user will be able to type any value for it.
+
+### Advanced variable options
+
+For Pre-Defined variable lines, you can use `---` to customize the behavior of `fzf`
+or how the value is going to be used.
+
+Below are examples of such customization:
+
+- 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>
+    
+    $ 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>
+
+    $ mapped: echo 'false true' | tr ' ' '\n' --- --map "grep -q t && echo 1 || echo 0"
+    ```
+
+
+The supported parameters are:
+
+| Parameter               | Description                                                                               |
+|:------------------------|:------------------------------------------------------------------------------------------|
+| `--column <number>`     | `<number>` is the column number to extract from the result.                               |
+| `--map <bash_code>`     | **_[EXPERIMENTAL]_** `<bash_code>` 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 <arg>` | **_[EXPERIMENTAL]_** `<arg>` 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`:
+
+| Parameter forwarded to `fzf` |
+|:-----------------------------|
+| `--multi`                    |
+| `--header-lines <number>`    |
+| `--delimiter <regex>`        |
+| `--query <text>`             |
+| `--filter <text>`            |
+| `--header <text>`            |
+| `--preview <bash_code>`      |
+| `--preview-window <text>`    |
+
+### Variable dependency
+
+Pre-Defined variables can refer other pre-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. `<variable>`).
+
+Below is an example of using implicit dependencies to construct a path:
+
+```sh
+# Should print /my/pictures/wallpapers
+echo "<wallpaper_folder>"
+
+$ pictures_folder: echo "/my/pictures"
+$ wallpaper_folder: echo "<pictures_folder>/wallpapers"
+```
+
+#### 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 <x>, the possible values of <y> will be "hello foo" and "hello bar"
+echo <x> <y>
+
+# If you want to ignore the contents of <x> and only print <y>
+: <x>; echo <y>
+
+$ x: echo "hello hi" | tr ' ' '\n'
+$ y: echo "$x foo;$x bar" | tr ';' '\n'
+```
+
+### Variable as multiple arguments
+
+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>
+
+$ 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
+
+$ pictures_folder: echo "/my/pictures"
+
+% wallpapers
+@ dirs, common
+
+# Should print /my/pictures/wallpapers
+echo "<pictures_folder>/wallpapers"
+
+% screenshots
+@ dirs, common
+
+# Should print /my/pictures/screenshots
+echo "<pictures_folder>/screenshots"
+```
+
+## Multiline commands/snippets
+
+Commands can be multiline, we call them snippets.
+
+- You can write them as follows:
+
+    ```sh
+    % bash, foo
+
+    # This will output "foo\nyes"
+    echo foo
+    true \
+       && echo yes \
+       || echo no
+    ```
+
+- Or, you can place them inside Markdown code blocks, delimited by triple backticks (```` ``` ````):
+
+    ````sh
+    % git, code
+    
+    # Change branch
+    ```sh
+    git checkout <branch>
+    ```
+    
+    $ branch: git branch | awk '{print $NF}'
+    ````
+
+
+## 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 `:: <some_alias>`:
+
+```bash
+% aliases
+
+# This is one command :: el
+echo lorem ipsum
+
+# This is another command :: ef
+echo foo bar
+```
+
+You could add something similar to this in your `.bashrc`-like file:
+
+```bash
+navialias() {
+    navi --query ":: $1" --best-match
+}
+
+alias el="navialias el"
+alias ef="navialias ef"
+```
+
+If you don't want to use these conventions, you can even add full comments in your aliases:
+
+```bash
+navibestmatch() {
+    navi --query "$1" --best-match
+}
+
+alias el="navibestmatch 'This is one command'"
+alias ef="navibestmatch 'This is another command'"
+```

docs/cheatsheet_repositories.md

@@ -1,75 +0,0 @@
-## Cheatsheet repositories
-
-- [Browsing through cheatsheet repositories](#browsing-through-cheatsheet-repositories)
-- [Importing cheatsheets](#importing-cheatsheets)
-- [Adding your own cheatsheets](#adding-your-own-cheatsheets)
-- [Submitting cheatsheets](#submitting-cheatsheets)
-- [Using cheatsheets from other tools](#using-cheatsheets-from-other-tools)
-- [Auto-updating repositories](#auto-updating-repositories)
-
-### Browsing through cheatsheet repositories
-
-You can find cheatsheet repositories with:
-
-```sh
-navi repo browse
-```
-
-### Importing cheatsheets
-
-You can import cheatsheets from any git repository that includes `.cheat` files:
-
-```sh
-navi repo add https://github.com/denisidoro/cheats
-```
-
-### Adding your own cheatsheets
-
-You can either start a git repo with cheatsheets and import it as described above or you can add them directly to [data_dir](https://github.com/soc/dirs-rs#Features)`/navi`.
-
-### Submitting cheatsheets
-
-The main repository for cheatsheets is [denisidoro/cheats](https://github.com/denisidoro/cheats). Feel free to open a PR there for me to include your contributions.
-
-In order to add your own repository as a featured cheatsheet repo, please [edit this file](https://github.com/denisidoro/cheats/edit/master/featured_repos.txt). This list will be displayed when `navi repo browse` is run.
-
-### Using cheatsheets from other tools
-
-![Demo](https://user-images.githubusercontent.com/3226564/91878474-bae27500-ec55-11ea-8b19-17876178e887.gif)
-
-You can use cheatsheets from [tldr](https://github.com/tldr-pages/tldr) by running:
-
-```sh
-navi --tldr <query>
-```
-
-You can use cheatsheets from [cheat.sh](https://github.com/chubin/cheat.sh) by running:
-
-```sh
-navi --cheatsh <query>
-```
-
-### Auto-updating repositories
-
-Right now, **navi** doesn't have support for auto-updating out of the box. However, you can achieve this by using `git` and `crontab`.
-
-First make sure you cloned your repo using `git` to the correct folder:
-
-```sh
-user="<user>"
-repo="<repo>"
-git clone "https://github.com/${user}/${repo}" "$(navi info cheats-path)/${user}__${repo}"
-```
-
-Then, add a cron job:
-
-```sh
-crontab -e
-*/0 11 * * * bash -c 'cd "$(/usr/local/bin/navi info cheats-path)/<user>__<repo>" && /usr/local/bin/git pull -q origin master'
-```
-
-Please note the cron job above is just an example and you should edit it accordingly:
-
-- In this example, the cron job is triggered every day at 11am. [crontab guru](https://crontab.guru/) may come in handy if you want to change this value
-- The full paths to `navi` and `git` may differ in your setup. Check their actual values using `which navi` and `which git`
-- Don't forget to replace `<user>__<repo>` with the actual folder name

docs/cheatsheet_syntax.md

@@ -1,184 +0,0 @@
-## Cheatsheet syntax
-
-- [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
-
-Cheatsheets are described in `.cheat` files that look like this:
-
-```sh
-% git, code
-
-# Change branch
-git checkout <branch>
-
-$ branch: git branch | awk '{print $NF}'
-```
-
-Lines starting with:
-
-- `%`: 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.
-
-### Variables
-
-The interface prompts for variable names inside brackets (eg `<branch>`).
-
-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 `<tab>` the query typed will be preferred. If you hit `<enter>` the selection will be preferred.
-
-### 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:
-
-```sh
-# This will pick the 3rd column and use the first line as header
-docker rmi <image_id>
-
-# Even though "false/true" is displayed, this will print "0/1"
-echo <mapped>
-
-$ 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 <number>`: extracts a single column from the selected result
-- `--map <bash_code>`: _(experimental)_ applies a map function to the selected variable value
-- `--prevent-extra`: _(experimental)_ limits the user to select one of the suggestions
-- `--fzf-overrides <arg>`: _(experimental)_ applies arbitrary `fzf` overrides
-- `--expand`: _(experimental)_ converts each line into a separate argument
-
-In addition, it's possible to forward the following parameters to `fzf`:
-
-- `--multi`
-- `--header-lines <number>`
-- `--delimiter <regex>`
-- `--query <text>`
-- `--filter <text>`
-- `--header <text>`
-- `--preview <bash_code>`
-- `--preview-window <text>`
-
-### Variable dependency
-
-The command for generating possible inputs can implicitly refer other variables by using the `<varname>` syntax:
-
-```sh
-# Should print /my/pictures/wallpapers
-echo "<wallpaper_folder>"
-
-$ pictures_folder: echo "/my/pictures"
-$ wallpaper_folder: echo "<pictures_folder>/wallpapers"
-```
-
-If you want to make dependencies explicit, you can use the `$varname` syntax:
-
-```sh
-# If you select "hello" for <x>, the possible values of <y> will be "hello foo" and "hello bar"
-echo <x> <y>
-
-# If you want to ignore the contents of <x> and only print <y>
-: <x>; echo <y>
-
-$ x: echo "hello hi" | tr ' ' '\n'
-$ y: echo "$x foo;$x bar" | tr ';' '\n'
-```
-
-### Extending cheatsheets
-
-With the `@ same tags from other cheatsheet` syntax you can reuse the same variable in multiple cheatsheets.
-
-```sh
-% dirs, common
-
-$ pictures_folder: echo "/my/pictures"
-
-% wallpapers
-@ dirs, common
-
-# Should print /my/pictures/wallpapers
-echo "<pictures_folder>/wallpapers"
-
-% screenshots
-@ dirs, common
-
-# Should print /my/pictures/screenshots
-echo "<pictures_folder>/screenshots"
-```
-
-### Multiline snippets
-
-Commands may be multiline:
-
-```sh
-# This will output "foo\nyes"
-echo foo
-true \
-   && echo yes \
-   || echo no
-```
-
-### Variable as multiple arguments
-
-```sh
-# This will result into: cat "file1.json" "file2.json"
-cat <jsons>
-
-$ jsons: find . -iname '*.json' -type f -print --- --multi --expand
-```
-### Aliases
-
-**navi** doesn't have support for aliases as first-class citizens at the moment.
-
-However, it is trivial to create aliases using **navi** + a few conventions.
-
-For example, suppose you decide to end some of your commands with `:: <some_alias>`:
-
-```bash
-% aliases
-
-# This is one command :: el
-echo lorem ipsum
-
-# This is another command :: ef
-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:
-
-```bash
-navialias() {
-    navi --query ":: $1" --best-match
-}
-
-alias el="navialias el"
-alias ef="navialias ef"
-```
-
-If you don't want to use these conventions, you can even add full comments in your aliases:
-
-```bash
-navibestmatch() {
-    navi --query "$1" --best-match
-}
-
-alias el="navibestmatch 'This is one command'"
-alias ef="navibestmatch 'This is another command'"
-```

docs/config_file.md

@@ -1,37 +0,0 @@
-## Config file
-
-- [Example](#example)
-- [Location](#location)
-- [Creating the file](#creating-the-file)
-
-### Example
-
-An example config can be found by running:
-
-```sh
-navi info config-example
-```
-
-You can also read it online by clicking [here](./config_file_example.yaml).
-
-### Location
-
-Run the following command to check where the config file is/should be located:
-
-```sh
-navi info config-path
-```
-
-### Creating the file
-
-Run the following command to generate a config file with the default parameters:
-
-```sh
-navi info config-example > "$(navi info config-path)"
-```
-
-### Logging
-
-The log file will be created under the same directory where the config locates.
-
-And you can use the `RUST_LOG` env to set the log level, e.g. `RUST_LOG=debug navi`.

docs/configuration/README.md

@@ -0,0 +1,233 @@
+# Configuring Navi
+
+Navi allows you to configure it with a YAML configuration.
+
+<!-- TOC -->
+* [Configuring Navi](#configuring-navi)
+  * [Paths and Environment Variables](#paths-and-environment-variables)
+    * [The default configuration file path](#the-default-configuration-file-path)
+    * [Cheatsheets paths](#cheatsheets-paths)
+      * [The default cheatsheets path](#the-default-cheatsheets-path)
+      * [Defining the cheatsheets path with the environment variable](#defining-the-cheatsheets-path-with-the-environment-variable)
+      * [Defining the cheatsheets path in the configuration file](#defining-the-cheatsheets-path-in-the-configuration-file)
+        * [[DEPRECATED] - Using the `path` directive](#deprecated---using-the-path-directive)
+  * [Customization](#customization)
+    * [Changing colors](#changing-colors)
+      * [fzf color scheme](#fzf-color-scheme)
+      * [Navi colors](#navi-colors)
+    * [Resizing columns](#resizing-columns)
+    * [Overriding fzf options](#overriding-fzf-options)
+      * [Overriding during cheats selection](#overriding-during-cheats-selection)
+      * [Overriding during values selection](#overriding-during-values-selection)
+      * [Overriding for all cases](#overriding-for-all-cases)
+  * [Defining your own delimiter](#defining-your-own-delimiter)
+<!-- TOC -->
+
+## Paths and Environment Variables
+
+On the technical side, navi uses the `directories-next` crate for rust,
+which defines platform-specific locations to store the configuration files,
+the cache and other types of files an application might need.
+
+> [!TIP]
+> For example, this is why cheatsheets are being stored in `~/Library/Application Support/navi` on macOS.
+
+> [!NOTE]
+> Interested on how `directories-next` works?\
+> Go see their `crates.io` page: [crates.io/crates/directories-next](https://crates.io/crates/directories-next)
+
+
+### The default configuration file path
+
+During the compilation of navi, the default configuration file path is set by the `$NAVI_CONFIG` environment variable.\
+If it is not set, it fallbacks to `~/.config/navi/config.yaml`.
+
+You can check your default configuration file path with the info subcommand,
+see [/docs/usage/commands/info/](/docs/usage/commands/info/README.md#default-configuration-path) for more details.
+
+### Cheatsheets paths
+
+Navi checks the paths in the following order until it finds a value:
+
+1. the `$NAVI_PATH` environment variable
+2. the configuration file
+3. The default value of navi
+
+#### The default cheatsheets path
+
+By default, navi stores the cheatsheets in the `~/.local/share/navi/cheats/` directory.
+
+You can check your default cheatsheets path with the info subcommand,
+see [/docs/usage/commands/info/](/docs/usage/commands/info/README.md#default-cheatsheets-path) for more details.
+
+#### Defining the cheatsheets path with the environment variable
+
+The cheatsheets path can be defined using the `$NAVI_PATH` environment variable in a colon-separated list, for example:
+
+```sh
+export NAVI_PATH='/path/to/a/dir:/path/to/another/dir:/yet/another/dir'
+```
+
+#### Defining the cheatsheets path in the configuration file
+
+You can define the cheatsheets path in the configuration file with the following syntax:
+
+```yaml
+cheats:
+  paths:
+    - /path/to/some/dir # on unix-like os
+    - F:\\path\\to\\dir # on Windows
+```
+
+##### [DEPRECATED] - Using the `path` directive
+
+Until `2.17.0`, you could define your cheatsheets path with the `path` directive with the following syntax:
+
+```yaml
+cheats:
+  path: /path/to/some/dir
+```
+
+The directive is now deprecated and will be removed in `2.27.0`.
+
+## Customization
+
+### Changing colors
+
+#### fzf color scheme
+
+You can change the color scheme of `fzf` by overriding fzf options.
+
+> [!NOTE]
+> See [@junegunn/fzf/wiki/Color-schemes](https://github.com/junegunn/fzf/wiki/Color-schemes) and
+> [#overriding-fzf-options](#overriding-fzf-options) for more details.
+
+#### Navi colors
+
+You can change the text color for each column of navi in the configuration file with the following syntax:
+
+```yaml
+style:
+  tag:
+    color: <your color for tags>
+  comment:
+    color: <your color for comments>
+  snippet:
+    color: <your color for snippets>
+```
+
+Below is an example of what to do if you'd like navi to look like the French flag:
+
+- `config.yaml`:
+
+  ```yaml
+  style:
+    tag:
+      color: blue
+    comment:
+      color: white
+    snippet:
+      color: red
+  ```
+
+- The result:
+
+  ![navi-custom-colors](https://github.com/user-attachments/assets/d80352c5-d888-43e6-927d-805a8de1a7e2)
+
+### Resizing columns
+
+You can change the column width of each column of navi in the configuration file with the following syntax:
+
+```yaml
+style:
+  tag:
+    width_percentage: <width relative to the terminal window>
+    min_width: <width as number of characters>
+  comment:
+    width_percentage: <width relative to the terminal window>
+    min_width: <width as number of characters>
+  snippet:
+    width_percentage: <width relative to the terminal window>
+    min_width: <width as number of characters>
+```
+
+### Overriding fzf options
+
+You can override fzf options for two different cases:
+
+- During the cheats selection
+
+  Navi exposes the `overrides` directive in the configuration file
+  and the `NAVI_FZF_OVERRIDES` environment variable.
+
+- During the pre-defined variable values selection
+
+  Navi exposes the `overrides_var` directive in the configuration file
+  and the `NAVI_FZF_OVERRIDES_VAR` environment variable.
+
+For all cases, navi exposes the `FZF_DEFAULT_OPTS` environment variable.
+
+#### Overriding during cheats selection
+
+If you want to do the override with `--height 3`,
+you can do it with the following syntax in the configuration file:
+
+```yaml
+finder:
+  command: fzf
+  overrides: --height 3
+```
+
+But you can also define the environment variable like this:
+
+```bash
+export NAVI_FZF_OVERRIDES='--height 3'
+```
+
+#### Overriding during values selection
+
+If you want to do the override with `--height 3`,
+you can do it with the following syntax in the configuration file:
+
+```yaml
+finder:
+  command: fzf
+  overrides_var: --height 3
+```
+
+But you can also define the environment variable like this:
+
+```bash
+export NAVI_FZF_OVERRIDES_VAR='--height 3'
+```
+
+#### Overriding for all cases
+
+You can define the environment variable like this:
+
+```bash
+export FZF_DEFAULT_OPTS="--height 3"
+```
+
+> [!NOTE]
+> See [@junegunn/fzf](https://github.com/junegunn/fzf#layout) for more details on `$FZF_DEFAULT_OPTS`.
+
+## Defining your own delimiter
+
+Navi allows you to define your own delimiter to parse the selected result for a variable in your cheats.\
+It is equivalent to defining `--delimiter` used with `--column`.
+
+You can define it as such:
+
+```yaml
+finder:
+  delimiter_var: <your-regex-delimiter> ### By default the expression is \s\s+
+```
+
+> [!CAUTION]
+> Defining the delimiter via the configuration file means that Navi will use this delimiter by default for
+> every variable using the `--column` instruction.
+
+You can override this configuration with the `--delimiter` instruction in the variable definition of your cheat.\
+See [/docs/cheatsheet/syntax/](/docs/cheatsheet/syntax/README.md#advanced-variable-options) for more details.
+

docs/contributions/README.md

@@ -0,0 +1,47 @@
+# Navi contributors
+
+This section is about the ways you can contribute to Navi and its ecosystem.
+
+<!-- TOC -->
+* [Navi contributors](#navi-contributors)
+  * [How to contribute to Navi](#how-to-contribute-to-navi)
+  * [Versioning Scheme](#versioning-scheme)
+  * [Deprecation of features](#deprecation-of-features)
+<!-- TOC -->
+
+## How to contribute to Navi
+
+You have multiple ways to contribute to navi, here are the documented ones:
+
+- [Write code for Navi](code/README.md)
+- [Write documentation for Navi](documentation/README.md)
+- [Open Bug tickets](bugs/README.md)
+
+Please see each section for more details.
+
+
+## Versioning Scheme
+
+| Type  | Description                                                                                      |
+|-------|--------------------------------------------------------------------------------------------------|
+| Major | Anything which introduces a major breaking change. The bash to rust rewrite was such an example. |
+| Minor | Almost everything.                                                                               |
+| Fix   | A fix, just like its name. It should be micro releases with minimal changes.                     |
+
+## Deprecation of features
+
+Once you introduce a feature, you need to have a clear view of when we're
+going to remove its support within navi.
+
+In order to offer stability to the users, we prefer having 10 minor versions
+between the deprecation notice and the removal of its support.
+
+````txt
+Version where the feature is being deprecated: 0.10.0
+Version where the support is dropped: 0.20.0
+````
+
+> [!NOTE]
+> This rule is not absolute and each feature deprecation needs to be handled
+> carefully given its own circumstances, but try to stick as close as possible
+> to this rule.

docs/contributions/bugs/README.md

@@ -0,0 +1,6 @@
+# Contribute in opening bug tickets
+
+Like any other software, navi has bugs.
+
+If you encounter an issue with Navi, we encourage you to open a bug ticket.\
+Please see [https://github.com/denisidoro/navi/issues/](https://github.com/denisidoro/navi/issues/) to open an issue.

docs/contributions/code/README.md

@@ -0,0 +1,50 @@
+# Contribute code to Navi
+
+Navi is written in Rust, the widgets may be written in any language given it can be integrated with Navi.
+
+If you take the example of the most common widgets for Navi they are written in their shell scripting language
+because they intend to integrate Navi with the shell in question (Fish, Zsh, NuShell, PowerShell, etc.).
+
+We separate Navi into two categories:
+
+- `Navi Core` which refers to Navi's code in Rust
+- `Navi Widgets` which refers to code that intends to integrate Navi with a 3rd-party software
+
+## Contribute to Navi Core
+
+If you want to contribute to Navi Core there are certain steps you need to follow for
+your changes to be accepted.
+
+1. First, open an issue if no opened issues are related to the change you want to contribute.
+2. [Optional] Wait to have an opinion from the maintainers, developers or contributors from Navi.
+
+   > This step is marked as *Optional* as you can open a Merge Request (MR)/Pull Request (PR)  
+   > without having to open an issue beforehand, although it is recommended to not do so.
+
+   We ask you to wait before working on a PR as the way you see a feature and its implementation
+   might not be similar on how a maintainer of Navi sees it.
+
+   This will save you and the maintainers time.
+
+3. Fork the repository and iterate over your changes.
+4. Update Navi documentation
+
+    If you implement a new feature, you will need to create a new entry in the project's
+    documentation for users to know what has changed.
+
+    No significant modification in Navi's behaviour should be merged without being documented.\
+    For more details I recommend you to see [contributions/documentation/](../documentation/README.md).
+
+5. Open a PR on [denisidoro/navi](https://github.com/denisidoro/navi/pulls) and request a review
+6. [Optional] Your PR needs revisions and changes before it can be merged
+
+    It's not rare that your PR will need changes before it can be accepted by the maintainers
+    and then merged into the main branch.
+
+7. Your PR has been merged    
+
+    Congratulations! Your PR has been reviewed and merged, you should be proud of it,
+    and we thank you for your contribution.
+
+    The next release cycle will package all contributions into a new release and users
+    throughout the world will be able to use your new feature(s).

docs/contributions/documentation/README.md

@@ -0,0 +1,32 @@
+# Contribute documentation to Navi
+
+If you don't want or can't code in Rust, we welcome all contributions,
+even more so if it's related to documentation.
+
+The documentation of Navi is currently made in Markdown.
+
+## Markdown documentation
+
+The documentation source files are located in the `docs/` folder and are mainly grouped by features.
+The current documentation follows a structure where one folder equals one topic.
+
+Here is a quick representation of the folder structure this documentation currently follows:
+
+```txt
+.
++-- docs
+|   +-- examples
+|   |   +-- <topic-examples>
+|   +-- src
+|   |   +-- <topic-source-files>
+|   |   |   +-- <sorted-by-type>
+|   +-- <topic>
+|   |   +-- README.md
+```
+
+You can see that we have separated the `src` and `examples` folder from the topic with the intent to make it
+easier to find each type of documentation.
+
+> [!NOTE]
+> It is recommended to not go deeper than 3 levels in the documentation.
+

docs/customization.md

@@ -1,40 +0,0 @@
-## Customization
-
-- [Changing colors](#changing-colors)
-- [Resizing columns](#resizing-columns)
-- [Overriding fzf options](#overriding-fzf-options)
-
-### Changing colors
-
-You can change the [color scheme](https://github.com/junegunn/fzf/wiki/Color-schemes) by [overriding fzf options](#overriding-fzf-options).
-
-In addition, you can change the text color for each column by properly configuring _navi_'s `config.yaml`. Please check `navi --help` for more instructions.
-
-### Resizing columns
-
-You can change the column widths by properly configuring _navi_'s `config.yaml`. Please check `navi --help` for more instructions.
-
-### Overriding fzf options
-
-Let's say you want to override [$FZF_DEFAULT_OPTS](https://github.com/junegunn/fzf#layout) with `--height 3`.
-
-This can be overridden in the following ways:
-
-```sh
-# if you want to override only when selecting snippets
-navi --fzf-overrides '--height 3'
-
-# alternatively, using an environment variable in your .bashrc-like file:
-export NAVI_FZF_OVERRIDES='--height 3'
-
-# if you want to override only when selecting argument values
-navi --fzf-overrides-var '--height 3'
-
-# alternatively, using an environment variable in your .bashrc-like file:
-export NAVI_FZF_OVERRIDES_VAR='--height 3'
-
-# if you want to override for all cases
-FZF_DEFAULT_OPTS="--height 3" navi
-```
-
-In addition, this can be set by properly configuring _navi_'s `config.yaml`. Please check `navi --help` for more instructions.

docs/deprecated/Alfred/README.md

@@ -1,15 +1,15 @@
-## Alfred
+# Alfred 
+
+> [!CAUTION]
+> This feature has been deprecated and support has been dropped since 2.16.0.
+>
+> The latest version with support is [2.15.1](https://github.com/denisidoro/navi/releases/tag/v2.15.1).
+
 
 This is _experimental_. If you face any issues, please report [here](https://github.com/denisidoro/navi/issues/348).
 
 ![Alfred demo](https://user-images.githubusercontent.com/3226564/80294838-582b1b00-8743-11ea-9eb5-a335d8eed833.gif)
 
-### Note
-
-Support for alfred has been removed.
-
-The latest version which has some support for it is [2.15.1](https://github.com/denisidoro/navi/releases/tag/v2.15.1).
-
 ### Instructions
 
 - make sure you have [Alfred Powerpack](https://www.alfredapp.com/powerpack/)

docs/examples/cheatsheet/example.cheat

@@ -1,6 +1,6 @@
-% first cheat
-
-# print something
-echo "My name is <name>!"
-
-$ name: whoami
+% first cheat
+
+# print something
+echo "My name is <name>!"
+
+$ name: whoami

docs/examples/configuration/config-example.yaml

@@ -17,19 +17,22 @@ finder:
   command: fzf # equivalent to the --finder option
   # overrides: --tac # equivalent to the --fzf-overrides option
   # overrides_var: --tac # equivalent to the --fzf-overrides-var option
+  # delimiter_var: \s\s+ # equivalent to the --delimiter option that is used with --column option when you extract a column from the selected result for a variable
 
 # cheats:
 #   paths:
 #     - /path/to/some/dir # on unix-like os
 #     - F:\\path\\to\\dir # on Windows
-# path: /path/to/some/dir # (DEPRECATED) equivalent to the --path option
 
 # search:
-# tags: git,!checkout # equivalent to the --tag-rules option
+#   tags: git,!checkout # equivalent to the --tag-rules option
+
+# client:
+#   tealdeer: true # enables tealdeer support for navi --tldr
 
 shell:
   # Shell used for shell out. Possible values: bash, zsh, dash, ...
   # For Windows, use `cmd.exe` instead.
   command: bash
-  
+
   # finder_command: bash # similar, but for fzf's internals

docs/installation.md

@@ -1,142 +0,0 @@
-## Installation
-
-- [Installing the main binary](#installing-the-main-binary)
-  - [Using Homebrew](#using-homebrew)
-  - [Using Gentoo](#using-gentoo)
-  - [Using nix](#using-nix)
-  - [Using cargo](#using-cargo)
-  - [Using install script](#using-install-script)
-  - [Downloading pre-compiled binaries](#downloading-pre-compiled-binaries)
-  - [Building from source](#building-from-source)
-  - [Other package managers](#other-package-managers)
-- [Installing the shell widget](#installing-the-shell-widget)
-
-### Installing the main binary
-
-#### Using [Homebrew](http://brew.sh/)
-
-```sh
-brew install navi
-```
-
-#### Using [Gentoo](https://gentoo.org/)
-
-Be sure to [enable](https://wiki.gentoo.org/wiki/Ebuild_repository) the [GURU overlay](https://gpo.zugaina.org/Overlays/guru/app-misc/navi).
-
-```sh
-emerge -a app-misc/navi
-```
-
-#### Using [pacman](https://wiki.archlinux.org/title/Pacman)
-
-```sh
-pacman -S navi
-```
-
-#### Using [nix](https://nixos.org/)
-
-```sh
-nix-env -iA nixpkgs.navi
-```
-
-#### Using [cargo](https://github.com/rust-lang/cargo)
-
-```bash
-cargo install --locked navi
-```
-
-#### Using [choco](https://community.chocolatey.org/packages/navi)
-
-For Windows user, using powershell
-
-1. Install package via choco
-   ```bash
-   choco install navi
-   ```
-2. Create `$env:USERPROFILE\AppData\Roaming\navi\config.yaml` and override `shell.command` as per [config_file_example.yaml](./config_file_example.yaml)
-
-   ```
-   style:
-     tag:
-       color: cyan
-     comment:
-       color: grey
-     snippet:
-       color: white
-
-   shell:
-     command: powershell
-   ```
-
-   Remark: Above example also adds custom colors for better readability in case you use standard blue for your Powershell
-
-#### Using install script
-
-```bash
-bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)
-
-# (optional) to set directories:
-# BIN_DIR=/usr/local/bin bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)
-```
-
-#### Downloading pre-compiled binaries
-
-- download the correct binary [here](https://github.com/denisidoro/navi/releases/latest)
-- extract the content to your `$PATH`
-
-#### Building from source
-
-```bash
-git clone https://github.com/denisidoro/navi ~/.navi
-cd ~/.navi
-make install
-
-# (optional) to set the install directory:
-# make BIN_DIR=/usr/local/bin install
-```
-
-##### Compile time environment variables
-
-**navi** supports environment variables at compile time that modify the behavior of the binary at runtime:
-
-- `NAVI_PATH` (directory path value): If the `cheats` directory in the user's directory does not exist, **navi** uses this path (if it exists), as a fallback location to look for cheat files. Use case: system-wide installed, shared used cheatsheets folder.
-- `NAVI_CONFIG` (file path value): If the `config.yaml` file in the user's directory does not exist, **navi** uses this path (if it exists), as a fallback location to look for a configuration file. Use case: system-wide installed, shared used configuration file.
-
-#### Other package managers
-
-You can find **navi** for more package managers by clicking on the image below:
-
-[![Packaging status](https://repology.org/badge/vertical-allrepos/navi.svg)](https://repology.org/project/navi/versions)
-
-Feel free to be the maintainer of **navi** for any package manager you'd like!
-
-### Installing the shell widget
-
-If you want to install it, add this line to your `.bashrc`-like file:
-
-```sh
-# bash
-eval "$(navi widget bash)"
-
-# zsh
-eval "$(navi widget zsh)"
-
-# fish
-navi widget fish | source
-
-# elvish
-eval (navi widget elvish | slurp)
-
-# xonsh
-# xpip install xontrib-navi # ← run in your xonsh session to install xontrib
-xontrib load navi # ← add to your xonsh run control file
-```
-
-By default, `Ctrl+G` is assigned to launching **navi** (in xonsh can be customized with `$X_NAVI_KEY`, see [xontrib-navi](https://github.com/eugenesvk/xontrib-navi) for details).
-
-There's currently no way to customize the widget behavior out-of-the-box. If you want to change the keybinding or the **navi** flags used by the widget, please:
-
-1. run, e.g., `navi widget bash` in your terminal
-2. copy the output
-3. paste the output in your `.bashrc`-like file
-4. edit the contents accordingly

docs/installation/README.md

@@ -0,0 +1,147 @@
+# Installation of navi
+
+This is a reference of all known methods to install navi.
+
+> [!CAUTION]
+> Navi, as of now, has only two official builds, the released binaries on GitHub
+> and the published package on brew.
+> 
+> All the other packages are community-maintained.
+
+## Using package managers
+
+### Homebrew
+
+```sh
+brew install navi
+```
+
+> [!NOTE]
+> See [brew.sh](https://brew.sh/) for more details.
+
+### Using Gentoo
+
+> [!WARNING]
+> You need to enable the GURU overlay for the instructions below to work correctly.
+> 
+> For more details see:
+> 
+> - [wiki.gentoo.org/wiki/Ebuild_repository](https://wiki.gentoo.org/wiki/Ebuild_repository)
+> - [gpo.zugaina.org/Overlays/guru/app-misc/navi](https://gpo.zugaina.org/Overlays/guru/app-misc/navi).
+
+```sh
+emerge -a app-misc/navi
+```
+
+> [!NOTE]
+> See [Gentoo.org](https://gentoo.org/) for more details.
+
+### Using Pacman
+
+```sh
+pacman -S navi
+```
+
+> [!NOTE]
+> See [wiki.archlinux.org/title/Pacman](https://wiki.archlinux.org/title/Pacman) for more details.
+
+### Using nix
+
+```sh
+nix-env -iA nixpkgs.navi
+```
+
+> [!NOTE]
+> See [nixos.org](https://nixos.org/) for more details
+
+### Using Cargo
+
+```bash
+cargo install --locked navi
+```
+
+> [!NOTE]
+> See [@rust-lang/cargo](https://github.com/rust-lang/cargo) for more details.
+
+### Using Chocolatey
+
+```bash
+choco install navi
+```
+
+> [!CAUTION]
+> You currently need to create the config file `$env:USERPROFILE\AppData\Roaming\navi\config.yaml`
+> and define the `shell.command` directive as `powershell` for navi to work correctly.
+> 
+> ```yaml
+> shell:
+>   command: powershell
+> ```
+
+> [!NOTE]
+> See [community.chocolatey.org](https://community.chocolatey.org) for more details.
+
+## Using the installation script
+
+Navi has an installation script ready for you to use, you can call it like this:
+
+```bash
+bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)
+```
+
+If you need to define the directory for the binary, you can call it like this:
+
+```bash
+BIN_DIR=/usr/local/bin bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)
+```
+
+## Downloading pre-compiled binaries
+
+With each release, we try our best to build and publish a binary for each
+supported platform, you can find them here:
+[@denisidoro/navi/releases/latest](https://github.com/denisidoro/navi/releases/latest)
+
+What you need to do is:
+
+- to download the binary corresponding to the version you want to install
+- to extract the content of the archive to your `$PATH`
+
+## Building from source
+
+You can also build navi from source, it's mainly used by contributors to
+test their modifications but can be used by end users who want to build their own version.
+
+- You need to clone the repository:
+
+    ```bash
+    git clone https://github.com/denisidoro/navi && cd navi
+    ```
+
+- Call `make`
+
+    ```bash
+    make install
+    ```
+
+You can specify the binary directory with:
+
+```bash
+make BIN_DIR=/usr/local/bin install
+```
+
+## Compile time environment variables
+
+**navi** supports environment variables at compile time that will modify the behavior of navi at runtime, they are:
+
+| Environment variable | Description                                                 |
+|----------------------|-------------------------------------------------------------|
+| `NAVI_PATH`          | This defines the default path used by navi for cheatsheets. |
+| `NAVI_CONFIG`        | This defines the default configuration file used by navi.   |
+
+## Other package managers
+
+You can find **navi** for more package managers by clicking on the image below:
+
+[![Packaging status](https://repology.org/badge/vertical-allrepos/navi.svg)](https://repology.org/project/navi/versions)
+
+Feel free to be the maintainer of **navi** for any package manager you'd like!

docs/navi_config.md

@@ -1,32 +0,0 @@
-## Config file path
-
-The default config file path is set by the `$NAVI_CONFIG` environment variable. If it is not set, it fallbacks to `~/.config/navi/config.yaml`. The command
-```sh
-navi info config-path
-```
-prints which config file path is being used. You can get an config file example by running
-```sh
-navi info config-example
-```
-or by clicking [here](./config_file_example.yaml). To turn this example your config file, run
-
-```sh
-navi info config-example > "$(navi info config-path)"
-```
-## Cheat sheet paths
-
-The default `.cheat` files paths are defined in the `$NAVI_PATH` environment variable in a colon-separated list, e.g.,
-```sh
-export NAVI_PATH='/path/to/a/dir:/path/to/another/dir:/yet/another/dir'
-```
-If this environment variable is unset or if all directories do not exist, `navi` uses that paths defined in its config files. Finally, if there is no config file or if the `.cheat` file paths was not set, the default `.cheat` file paths fallbacks to `~/.local/share/navi/cheats/`. The command
-```sh
-navi info cheats-path
-```
-prints to you all paths used to search for `.cheat` files. 
-
-You can also add other paths at runtime by running `navi` with the `--path` option and a colon-separed paths list, e.g.,
-```sh
-navi --path '/some/dir:/other/dir'
-```
-It's irrelevant the directory structure within each path. They can even be all in a single file if you wish, as long as you split them accordingly with lines starting with `%`.

docs/paths_and_env_vars.md

@@ -1,25 +0,0 @@
-# Paths and Environment Variables
-
-Navi uses the [`directories-next`](https://crates.io/crates/directories-next) package, which 
-defines platform-specific standard locations of directories for config, cache and other data.
-
-Mac users, this is why your files are being stored in `~/Library/Application Support/navi`.
-
-To set custom paths for your config and cheat sheets, you can set the following
-environment variables:
-
-```zsh
-export NAVI_CONFIG="~/.config/navi/config.yaml"
-export NAVI_PATH="~/.local/share/navi"
-```
-Despite `$NAVI_PATH` being set, it will not be used when installing cheat
-sheets directly via navi's own commands. 
-
-For example when running `navi add repo <repo>`, the default paths as per the `directories-next` 
-package will still be used.
-
-To avoid this, you may simply clone repos via a regular `git clone` command,
-directly into `$NAVI_PATH`.
-
-Note! `navi info cheats-path` and `navi info config-path` display the *default* path, not 
-the path set by the user. [It is known that this is a little misleading!](https://github.com/denisidoro/navi/issues/664#issuecomment-1004721178).

docs/shell_scripting.md

@@ -1,40 +0,0 @@
-## Using it for shell scripting
-
-For a real world scenario example, please check this [blog post](https://denisidoro.github.io/posts/cli-templates/).
-
-Let's say you want to write a bash script that, among other things, asks the user to write the name of a git branch that should be checked out.
-
-If you already have the [cheatsheet above](#cheatsheet-syntax), then you could write the following in your script:
-
-```sh
-navi --query "change branch" --best-match
-```
-
-**navi** will ask the user to fill all arguments needed.
-
-If you want to set the `<branch>` beforehand in your script:
-
-```sh
-branch="master" navi --query "change branch" --best-match
-```
-
-- no interactive input will be shown
-- the value for `<branch>` will be exactly the one passed as argument
-
-If you want to filter some results for `<branch>`:
-
-```sh
-branch__query="master" navi --query "change branch" --best-match
-```
-
-- an interactive input will be shown, unless a single entry is autoselected
-- the value for `<branch>` will be the one selected
-
-If you want to select the best match for `<branch>`:
-
-```sh
-branch__best="master" navi --query "change branch" --best-match
-```
-
-- no interactive input will be shown
-- the value for `<branch>` will be the one that best matches the one passed as argument

docs/tmux.md

@@ -1,37 +0,0 @@
-## Tmux
-
-You can use **navi** as a [Tmux](https://github.com/tmux/tmux/wiki) widget to reach your Vim commands, often used SQL queries, etc. in any command-line app even in SSH sessions.
-
-Add these lines to your Tmux config file to access **navi** by pressing `prefix + C-g`.
-
-```sh
-bind-key -T prefix C-g split-window \
-  "$SHELL --login -i -c 'navi --print | head -n 1 | tmux load-buffer -b tmp - ; tmux paste-buffer -p -t {last} -b tmp -d'"
-```
-
-Example cheatsheet:
-
-```sh
-% vim 
-
-# Quit without save
-qa!
-
-# Delete a paragraph
-normal dap
-
-# Generate sequence of numbers
-put =range(<start>, <stop>)
-
-% postgresql
-
-# Describe table columns in `psql` or `pgcli`
-select 
-   table_name, 
-   column_name, 
-   data_type 
-from 
-   information_schema.columns
-where 
-   table_name = '<table>';
-```

docs/usage/README.md

@@ -0,0 +1,28 @@
+# The usage of Navi
+
+Navi can be used in multiple ways
+
+#### Defining the cheatsheets path at runtime
+
+You can define the paths to use for cheatsheets at runtime using the `--path` parameter and a colon-separated paths list
+
+For example, if we want to search for cheatsheets in `/some/dir` and in `/other/dir`:
+
+```sh
+navi --path '/some/dir:/other/dir'
+```
+
+## Logging
+
+The log file will be created under the same directory where the configuration file is located.\
+You can use the `RUST_LOG` environment variable to set the log level.
+
+For example, to have the logging in debug mode when running navi:
+
+```bash
+RUST_LOG=debug navi
+```
+
+> [!NOTE]
+> If the directory of the configuration file doesn't exist, no log file
+> is going to be created.

docs/usage/commands/info/README.md

@@ -0,0 +1,66 @@
+# The info subcommands of navi
+
+Navi exposes information about its default values or examples for you to use.
+
+<!-- TOC -->
+* [The info subcommands of navi](#the-info-subcommands-of-navi)
+  * [Commands Reference](#commands-reference)
+  * [Default configuration information](#default-configuration-information)
+    * [Default configuration path](#default-configuration-path)
+    * [Example configuration file](#example-configuration-file)
+  * [Default cheatsheets path](#default-cheatsheets-path)
+<!-- TOC -->
+
+## Commands Reference
+
+| Command             | Description                                        |
+|---------------------|----------------------------------------------------|
+| config-path         | [DEPRECATED] Lets you see the default config path  |
+| cheats-path         | [DEPRECATED] Lets you see the default cheats path  |
+| default-config-path | Lets you see the default config path               |
+| default-cheats-path | Lets you see the default cheats path               |
+| config-example      | Lets you see an example for the configuration file |
+| cheats-example      | Lets you see an example for a cheat file           |
+
+## Default configuration information
+
+### Default configuration path
+
+Navi exposes its default configuration path with:
+
+```sh
+navi info config-path
+```
+
+> [!NOTE]
+> See [/docs/configuration/](/docs/configuration/README.md#the-default-configuration-file-path) for more details on how the default configuration path is defined.
+
+### Example configuration file
+
+Navi lets you get an example configuration file with:
+
+```sh
+navi info config-example
+```
+
+> [!NOTE]
+> You can retrieve this file at the following address: [/docs/examples/configuration/config-example.yaml](/docs/examples/configuration/config-example.yaml)
+
+For example, you can use this command to create the default configuration file,
+if not already present:
+
+```sh
+navi info config-example > "$(navi info config-path)"
+```
+
+## Default cheatsheets path
+
+Navi exposes its default cheatsheets path with:
+
+```sh
+navi info cheats-path
+```
+
+> [!NOTE]
+> See [/docs/configuration/](/docs/configuration/README.md#the-default-cheatsheets-path) for more details on how the cheatsheets path is defined.
+

docs/usage/commands/repo/README.md

@@ -0,0 +1,48 @@
+# The repo subcommands of navi
+
+<!-- TOC -->
+* [The repo subcommands of navi](#the-repo-subcommands-of-navi)
+  * [Commands Reference](#commands-reference)
+  * [Browsing through cheatsheet repositories](#browsing-through-cheatsheet-repositories)
+  * [Importing cheatsheet repositories](#importing-cheatsheet-repositories)
+<!-- TOC -->
+
+## Commands Reference
+
+| Command | Description                                                       |
+|---------|-------------------------------------------------------------------|
+| add     | Lets you import a cheatsheet repository                           |
+| browser | Lets you browse through a curated list of cheatsheet repositories |
+
+## Browsing through cheatsheet repositories
+
+Navi lets you browse featured [GitHub](https://github.com) repositories registered in [@denisidoro/cheats/featured_repos.txt](https://github.com/denisidoro/cheats/blob/master/featured_repos.txt).
+
+You can find them within navi with the following command:
+
+```sh
+navi repo browse
+```
+
+## Importing cheatsheet repositories
+
+You can import `cheatsheet repositories` using a working git-clone format.\
+This includes using an HTTPS URL or an SSH URI.
+
+- Import using HTTPS
+
+    ```sh
+    navi repo add https://github.com/denisidoro/cheats
+    ```
+
+- Import using SSH
+
+    ```shell
+    navi repo add git@github.com:denisidoro/cheats
+    ```
+
+> [!CAUTION]
+> Despite `$NAVI_PATH` being set, it will not be used when installing cheat sheets directly via navi's own commands.\
+> For example when running `navi add repo <repo>`, the default paths will still be used.
+> 
+> To avoid this, you may simply clone repos via a regular `git clone` command, directly into `$NAVI_PATH`.

docs/usage/fzf-overrides/README.md

@@ -0,0 +1,30 @@
+# The FZF Overrides of Navi
+
+Navi allows you to override certain parts of FZF in multiple ways.
+
+<!-- TOC -->
+* [The FZF Overrides of Navi](#the-fzf-overrides-of-navi)
+  * [Command line arguments](#command-line-arguments)
+  * [Environment variables](#environment-variables)
+<!-- TOC -->
+
+## Command line arguments
+
+Navi allows you to use command line arguments in order to override fzf values:
+
+```sh
+# if you want to override only when selecting snippets
+navi --fzf-overrides '--height 3'
+
+# if you want to override only when selecting argument values
+navi --fzf-overrides-var '--height 3'
+```
+
+## Environment variables
+
+Navi allows you to use environment variables in order to override fzf values.
+
+```bash
+# if you want to override for all cases
+FZF_DEFAULT_OPTS="--height 3" navi
+```

docs/usage/shell-scripting/README.md

@@ -0,0 +1,58 @@
+# Navi and shell scripting
+
+You can use Navi with shell scripting.
+
+<!-- TOC -->
+* [Navi and shell scripting](#navi-and-shell-scripting)
+  * [Simply calling a cheat](#simply-calling-a-cheat)
+  * [Defining variables while calling](#defining-variables-while-calling)
+  * [Filtering results for a variable](#filtering-results-for-a-variable)
+  * [Selecting the best match for a variable](#selecting-the-best-match-for-a-variable)
+<!-- TOC -->
+
+> [NOTE!]
+> The following blog post gives you an example of a real world scenario: [denisidoro.github.io/posts/cli-templates/](https://denisidoro.github.io/posts/cli-templates/)
+
+
+## Simply calling a cheat
+
+Below is an example on how to call a cheat from within navi:
+
+```sh
+navi --query "change branch" --best-match
+```
+
+> [!NOTE]
+> Navi will ask the user to fill all arguments/variables needed.
+
+## Defining variables while calling
+
+If you want to set the `<branch>` beforehand in your script, you can do as follows:
+
+```sh
+branch="master" navi --query "change branch" --best-match
+```
+
+Navi will not show any interactive input and `<branch>` will be exactly the one defined while calling.
+
+## Filtering results for a variable
+
+If you want to filter some results for `<branch>`, you can do as follows:
+
+```sh
+branch__query="master" navi --query "change branch" --best-match
+```
+
+Navi will show any interactive input, unless a single entry is automatically selected and
+the value for `<branch>` will be the one selected by the user.
+
+## Selecting the best match for a variable
+
+If you want to select the best match for `<branch>`, you can do as follows:
+
+```sh
+branch__best="master" navi --query "change branch" --best-match
+```
+
+Navi will not show any interactive input, and the value for `<branch>` will be the one that
+best matches the value passed as argument.

docs/widgets/README.md

@@ -0,0 +1,71 @@
+# Navi widgets
+
+You want to launch Navi with a shortcut?\
+Widgets are here for you!
+
+Widgets are 3rd-party contributions and integrates Navi with 3rd-party software such as shells.
+
+## List of shell widgets
+
+| Shell      | Navi support       |
+|------------|--------------------|
+| Bash       | :white_check_mark: |
+| Fish       |                    |
+| Zsh        |                    |
+| NuShell    | :white_check_mark: |
+| PowerShell | :white_check_mark: |
+
+## PowerShell Widget
+
+- Removal
+
+```powershell
+Remove-Module navi.plugin
+```
+
+## Other widgets
+
+- Tmux
+- Vim
+
+
+### Installing the shell widget
+
+If you want to install it, add this line to your `.bashrc`-like file:
+
+```sh
+# bash
+eval "$(navi widget bash)"
+
+# zsh
+eval "$(navi widget zsh)"
+
+# fish
+navi widget fish | source
+
+# elvish
+eval (navi widget elvish | slurp)
+
+# xonsh
+# xpip install xontrib-navi # ← run in your xonsh session to install xontrib
+xontrib load navi # ← add to your xonsh run control file
+```
+
+#### Nushell
+
+Due to Nushell's [unique design](https://www.nushell.sh/book/thinking_in_nu.html#think-of-nushell-as-a-compiled-language), it is not possible to `eval` a piece of code dynamically like in other shells therefore the integration process is a bit more involved. Here is an example:
+1. run `^navi widget nushell | save ($nu.default-config-dir | path join "navi-integration.nu")`
+2. add the following lines to `config.nu`:
+    ```nushell
+    source ($nu.default-config-dir | path join "navi-integration.nu")
+    ```
+
+
+By default, `Ctrl+G` is assigned to launching **navi** (in xonsh can be customized with `$X_NAVI_KEY`, see [xontrib-navi](https://github.com/eugenesvk/xontrib-navi) for details).
+
+There's currently no way to customize the widget behavior out-of-the-box. If you want to change the keybinding or the **navi** flags used by the widget, please:
+
+1. run, e.g., `navi widget bash` in your terminal
+2. copy the output
+3. paste the output in your `.bashrc`-like file
+4. edit the contents accordingly

docs/widgets/howto/TMUX.md

@@ -0,0 +1,49 @@
+# Tmux widget
+
+You can use **navi** as a [Tmux](https://github.com/tmux/tmux/wiki) widget to reach your Vim commands,
+often used SQL queries, etc. in any command-line app even in SSH sessions.
+
+<!-- TOC -->
+* [Tmux widget](#tmux-widget)
+  * [Keybinding navi](#keybinding-navi)
+  * [Example cheatsheet](#example-cheatsheet)
+<!-- TOC -->
+
+## Keybinding navi
+
+To be able to open navi via <kbd> prefix + C-g </kbd>, you need to add the following lines
+to your Tmux configuration file.
+
+```sh
+bind-key -N "Open Navi (cheat sheets)" -T prefix C-g split-window \
+  "$SHELL --login -i -c 'navi --print | tmux load-buffer -b tmp - ; tmux paste-buffer -p -t {last} -b tmp -d'"
+```
+
+## Example cheatsheet
+
+Here is an example cheatsheet to use inside Tmux:
+
+```sh
+% vim 
+
+# Quit without save
+qa!
+
+# Delete a paragraph
+normal dap
+
+# Generate sequence of numbers
+put =range(<start>, <stop>)
+
+% postgresql
+
+# Describe table columns in `psql` or `pgcli`
+select 
+   table_name, 
+   column_name, 
+   data_type 
+from 
+   information_schema.columns
+where 
+   table_name = '<table>';
+```

docs/widgets/howto/VIM.md

@@ -0,0 +1,23 @@
+# Vim widget
+
+<!-- TOC -->
+* [Vim widget](#vim-widget)
+  * [Syntax Highlighting](#syntax-highlighting)
+<!-- TOC -->
+
+## Syntax Highlighting
+
+If you want syntax highlighting support for Navi in Vim, you need to
+add those syntax rules to your syntax files such as at `$VIMRUNTIME/syntax/navi.vim`.
+
+The rules are defined based on the [Cheatsheet syntax](/docs/cheatsheet/syntax/README.md).
+
+Here is an example:
+
+```vim
+syntax match Comment "\v^;.*$"
+syntax match Statement "\v^\%.*$"
+syntax match Operator "\v^\#.*$"
+syntax match String "\v\<.{-}\>"
+syntax match String "\v^\$.*$"
+```

rust-toolchain.toml

@@ -1,3 +1,3 @@
 [toolchain]
-channel = "1.67.0"
+channel = "1.81.0"
 components = [ "rustfmt", "clippy" ]

scripts/dot

@@ -8,7 +8,17 @@ export CARGO_PATH="${NAVI_HOME}/core/Cargo.toml"
 
 # TODO: bump dotfiles + remove this fn
 log::note() { log::info "$@"; }
-export -f log::note
+
+cargo() {
+   if [ "${1:-}" = "install" ] && [ "${2:-}" = "cross" ]; then
+      shift 2 || true
+      command cargo install cross --git https://github.com/cross-rs/cross "$@"
+   else
+      command cargo "$@"
+   fi
+}
+
+export -f log::note cargo
 
 dot::clone() {
   git clone 'https://github.com/denisidoro/dotfiles' "$DOTFILES"
@@ -24,4 +34,4 @@ dot::clone_if_necessary() {
 
 dot::clone_if_necessary
 
-"${DOTFILES}/bin/dot" "$@"
+"${DOTFILES}/bin/dot" "$@"

scripts/install

@@ -251,14 +251,14 @@ install_navi() {
 
    elif command_exists brew; then
       brew install navi
-
-   elif command_exists cargo; then
-      cargo install navi
-
+   
    elif [[ -n "$target" ]]; then
       local -r version="$(latest_version_released)"
       download_asset "$version" "$target" || error_installing
 
+   elif command_exists cargo; then
+      cargo install navi
+
    else
       error_installing
 

scripts/release

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+### --------------------------------------------------------------------------------------------------------------------
+###     Logging functions
+### --------------------------------------------------------------------------------------------------------------------
+
+log::info() {
+  ### Will print `[INFO]` in black foreground colour and magenta background colour
+  ### then will print the given text in a magenta foreground colour and default background colour.
+  printf "\033[35m\033[7m[INFO]\033[27;39m \033[35m$*\033[39m\n"
+}
+
+log::error() {
+  ### Will print `[ERROR]` in black foreground colour and red background colour
+  ### then will print the given text in a red foreground colour and default background colour.
+  printf "\033[31m\033[7m[ERROR]\033[27;39m \033[31m$*\033[39m\n"
+}
+
+log::warn() {
+  ### Will print `[WARNING]` in black foreground colour and yellow background colour
+  ### then will print the given text in a yellow foreground colour and default background colour.
+  printf "\033[33m\033[7m[WARNING]\033[27;39m \033[33m$*\033[39m\n"
+}
+
+### --------------------------------------------------------------------------------------------------------------------
+###     Utils functions
+### --------------------------------------------------------------------------------------------------------------------
+
+### Permits us to know if the current target environment
+### is a windows platform or not.
+is_windows() {
+   local -r target="$1"
+   echo "$target" | grep -q "windows"
+}
+
+### NOTE: This function is currently not in use but kept as
+###       a backup function in case something breaks
+###
+### Returns the target environment, with a fix for the x86_64 target.
+get_env_target() {
+   eval "$(rustc --print cfg | grep target)"
+   local -rr raw="${target_arch:-}-${target_vendor:-}-${target_os:-}-${target_env:-}"
+
+   if echo "$raw" | grep -q "x86_64-apple-macos"; then
+      echo "x86_64-apple-darwin"
+   else
+      echo "$raw"
+   fi
+}
+
+### NOTE: This function is currently not in use but kept as
+###       a backup function in case something breaks
+###
+### Logs the given arguments then execute it
+_tap() {
+   log::info "$@"
+   "$@"
+}
+
+### NOTE: This function is currently not in use but kept as
+###       a backup function in case something breaks
+###
+### Lists the content of a path, given as parameter.
+_ls() {
+   log::info "contents from $*:"
+   ls -la "$@" || true
+}
+
+### --------------------------------------------------------------------------------------------------------------------
+###     Release-Related functions
+### --------------------------------------------------------------------------------------------------------------------
+
+release() {
+  local -r env_target="$1"
+  log::info "env target: $env_target"
+
+  local -r cross_target="${1:-"$env_target"}"
+  log::info "desired target: $cross_target"
+
+  TAR_DIR="$(pwd)/target/tar"
+
+  ### We clean up the target folder, just in case
+  rm -rf "$(pwd)/target" 2> /dev/null || true
+
+  ### We add the target for rustup in case cross doesn't find it.
+  ### Since the default behaviour of cross is to compile from
+  ### a rustup target if it doesn't find one for itself.
+  rustup target add $env_target
+  cargo install cross --locked
+
+  ### We're building the release via cross for the target environment
+  cross build --release --target "$env_target"
+
+  cd target/"$env_target"/release/
+
+  if is_windows "$env_target"; then
+    ### If our target is windows, we can simply zip our executable
+    ### since having tar is not the norm and neither the default
+    zip -r "navi.zip" "navi.exe"
+
+    ### We export a CI/CD variable to be used later in the pipeline
+    echo "EXTENSION=zip" >> $GITHUB_OUTPUT
+  else
+
+    ### @alexis-opolka - I'm currently disabling the usage of UPX since I cannot find how
+    ###     it was used before the merge of the code from the @denisidoro/dotfiles repository.
+    ###
+    #if upx --best --lzma "navi"; then
+    #  log::info "upx succeeded"
+    #else
+    #  log::info "upx failed"
+    #fi
+
+
+    ### For all other targets, they have tar as the norm
+    ### or have it installed by default.
+    tar -czf "navi.tar.gz" "navi"
+
+    ### We export a CI/CD variable to be used later in the pipeline
+    echo "EXTENSION=tar.gz" >> $GITHUB_OUTPUT
+  fi
+}
+
+### --------------------------------------------------------------------------------------------------------------------
+###     Main script
+### --------------------------------------------------------------------------------------------------------------------
+
+release "$@"

shell/navi.plugin.fish

@@ -1,29 +1,45 @@
 function _navi_smart_replace
-    set -l current_process (commandline -p | string trim)
-
-    if test -z "$current_process"
-        commandline -i (navi --print)
+    set --local query (commandline --current-process | string trim)
+    set --local version_parts ""
+    if test -n "$version"
+        set version_parts (string split '.' $version)
     else
-        set -l best_match (navi --print --best-match --query "$current_process")
+        set version_parts (string split '.' (string match -r '\d+\.\d+\.\d+' (fish --version)))
+    end
 
-        if not test "$best_match" >/dev/null
+    set --local force_repaint false
+    # https://github.com/fish-shell/fish-shell/blob/d663f553dffba460d6d0bcdf93df21bda9ec6f3f/doc_src/interactive.rst?plain=1#L440
+    #  > Bindings that change the mode are supposed to call the repaint-mode bind function
+    #
+    # Related issues
+    #  - https://github.com/fish-shell/fish-shell/issues/5033
+    #  - https://github.com/fish-shell/fish-shell/issues/5860
+    #  - https://github.com/fish-shell/fish-shell/blob/d663f553dffba460d6d0bcdf93df21bda9ec6f3f/src/screen.rs#L531
+    #
+    # Introduced with: https://github.com/denisidoro/navi/pull/982
+    if test $version_parts[1] -ge 4
+        set force_repaint true
+    end
+
+    if test -n "$query"
+        set --local best_match (navi --print --query "$query" --best-match)
+        if test -n "$best_match"
+            commandline --current-process $best_match
+            if test "$force_repaint" = true
+                commandline --function repaint
+            end
             return
         end
-
-        if test -z "$best_match"
-            commandline -p (navi --print --query "$current_process")
-        else if test "$current_process" != "$best_match"
-            commandline -p $best_match
-        else
-            commandline -p (navi --print --query "$current_process")
-        end
     end
 
-    commandline -f repaint
+    set --local candidate (navi --print --query "$query")
+    if test -n "$candidate"
+        commandline --current-process $candidate
+        if test "$force_repaint" = true
+            commandline --function repaint
+        end
+    end
 end
 
-if test $fish_key_bindings = fish_default_key_bindings
-    bind \cg _navi_smart_replace
-else
-    bind -M insert \cg _navi_smart_replace
-end
+bind \cg _navi_smart_replace
+bind --mode insert \cg _navi_smart_replace

shell/navi.plugin.nu

@@ -0,0 +1,34 @@
+export def navi_widget [] {
+    let current_input = (commandline)
+    let last_command = ($current_input | navi fn widget::last_command | str trim)
+
+    match ($last_command | is-empty) {
+        true => {^navi --print | complete | get "stdout"}
+        false => {
+            let find = $"($last_command)_NAVIEND"
+            let replacement = (^navi --print --query $'($last_command)' | complete | get "stdout")
+
+            match ($replacement | str trim | is-empty) {
+                false => {$"($current_input)_NAVIEND" | str replace $find $replacement}
+                true => $current_input
+            }
+        }
+    } 
+    | str trim
+    | commandline edit --replace $in
+    
+    commandline set-cursor --end
+}
+
+let nav_keybinding = {
+    name: "navi",
+    modifier: control,
+    keycode: char_g,
+    mode: [emacs, vi_normal, vi_insert],
+    event: {
+        send: executehostcommand,
+        cmd: navi_widget,
+    }
+}
+
+$env.config.keybindings = ($env.config.keybindings | append $nav_keybinding)

shell/navi.plugin.ps1

@@ -0,0 +1,56 @@
+
+
+$null = New-Module {
+
+    function Invoke-Navi {
+        $startArgs = @{
+            FileName = "navi";
+            Arguments = $args;
+            RedirectStandardOutput = $true;
+            WorkingDirectory = $PWD;
+            UseShellExecute = $false;
+        }
+        $p = [System.Diagnostics.Process]@{StartInfo = $startArgs}
+
+        [void]$p.Start()
+        $result = $p.StandardOutput.ReadToEnd()
+        $p.WaitForExit()
+
+        $result
+    }
+
+
+    ### Initial code from @lurebat (https://github.com/lurebat/)
+    ### See #570 (https://github.com/denisidoro/navi/issues/570) for its original contribution
+    function Invoke-NaviWidget {
+        $ast = $tokens = $errors = $cursor = $null
+        [Microsoft.PowerShell.PSConsoleReadLine]::GetBufferState([ref] $ast, [ref] $tokens, [ref] $errors, [ref] $cursor)
+
+        $line = $ast.ToString().Trim()
+        $output = $null
+
+        if ([String]::IsNullOrEmpty($line)) {
+            $output = (Invoke-Navi "--print" | Out-String).Trim()
+        }
+        else {
+            $best_match = (Invoke-Navi "--print --best-match --query `"$line`"" | Out-String).Trim()
+            if ([String]::IsNullOrEmpty($best_match)) {
+                $output = (Invoke-Navi "--print --query `"$line`"" | Out-String).Trim()
+            }
+            else {
+                $output = $best_match
+            }
+        }
+
+        [Microsoft.PowerShell.PSConsoleReadLine]::RevertLine()
+        [Microsoft.PowerShell.PSConsoleReadLine]::InvokePrompt()
+
+        ### Handling the case when the user escapes without selecting any entry
+        if (-Not([String]::IsNullOrEmpty($output))) {
+            [Microsoft.PowerShell.PSConsoleReadLine]::Insert([String]$output)
+        }
+    }
+
+    Set-PSReadlineKeyHandler -BriefDescription "A keybinding to open Navi Widget" -Chord Ctrl+g -ScriptBlock { Invoke-NaviWidget }
+    Export-ModuleMember -Function @()
+}

src/bin/main.rs

@@ -1,6 +1,6 @@
 extern crate navi;
 
-use dns_common::prelude::*;
+use crate::navi::prelude::*;
 use thiserror::Error;
 
 #[derive(Error, Debug)]

src/clients/cheatsh.rs

@@ -37,7 +37,7 @@ Make sure wget is correctly installed.";
 
     if let Some(0) = out.status.code() {
         let stdout = out.stdout;
-        let plain_bytes = strip_ansi_escapes::strip(stdout)?;
+        let plain_bytes = strip_ansi_escapes::strip(stdout);
 
         let markdown = String::from_utf8(plain_bytes).context("Output is invalid utf8")?;
         if markdown.starts_with("Unknown topic.") {

src/clients/tldr.rs

@@ -1,3 +1,4 @@
+use crate::config::CONFIG;
 use crate::prelude::*;
 use std::process::{Command, Stdio};
 
@@ -6,8 +7,9 @@ lazy_static! {
     pub static ref NON_VAR_CHARS_REGEX: Regex = Regex::new(r"[^\da-zA-Z_]").expect("Invalid regex");
 }
 
-static VERSION_DISCLAIMER: &str = "The tldr client written in C (the default one in Homebrew) doesn't support markdown files, so navi can't use it.
-The client written in Rust is recommended. The one available in npm works, too.";
+static VERSION_DISCLAIMER: &str =
+    "tldr-c-client (the default one in Homebrew) doesn't support markdown files, so navi can't use it.
+The recommended client is tealdeer(https://github.com/dbrgn/tealdeer).";
 
 fn convert_tldr_vars(line: &str) -> String {
     let caps = VAR_TLDR_REGEX.find_iter(line);
@@ -51,7 +53,9 @@ fn markdown_lines(query: &str, markdown: &str) -> Vec<String> {
 }
 
 pub fn call(query: &str) -> Result<Vec<String>> {
-    let args = [query, "--markdown"];
+    let tealdeer = CONFIG.tealdeer();
+    let output_flag = if tealdeer { "--raw" } else { "--markdown" };
+    let args = [query, output_flag];
 
     let child = Command::new("tldr")
         .args(args)
@@ -66,7 +70,6 @@ pub fn call(query: &str) -> Result<Vec<String>> {
             let msg = format!(
                 "navi was unable to call tldr.
 Make sure tldr is correctly installed.
-Refer to https://github.com/tldr-pages/tldr for more info.
 
 Note:
 {VERSION_DISCLAIMER}
@@ -86,9 +89,9 @@ Note:
         Ok(lines)
     } else {
         let msg = format!(
-            "Failed to call: 
+            "Failed to call:
 tldr {}
- 
+
 Output:
 {}
 
@@ -96,8 +99,9 @@ Error:
 {}
 
 Note:
-Please make sure you're using a version that supports the --markdown flag.
-If you are already using a supported version you can ignore this message. 
+The client.tealdeer config option can be set to enable tealdeer support.
+If you want to use another client, please make sure it supports the --markdown flag.
+If you are already using a supported version you can ignore this message.
 {}
 ",
             args.join(" "),

src/commands/core/actor.rs

@@ -63,7 +63,17 @@ fn prompt_finder(
 
     let exe = fs::exe_string();
 
-    let preview = if cfg!(target_os = "windows") {
+    let preview = if CONFIG.shell().contains("powershell") {
+        format!(
+            r#"{exe} preview-var {{+}} "{{q}}" "{name}"; {extra}"#,
+            exe = exe,
+            name = variable_name,
+            extra = extra_preview
+                .clone()
+                .map(|e| format!(" echo; {e}"))
+                .unwrap_or_default(),
+        )
+    } else if CONFIG.shell().contains("cmd.exe") {
         format!(
             r#"(@echo.{{+}}{eof}{{q}}{eof}{name}{eof}{extra}) | {exe} preview-var-stdin"#,
             exe = exe,

src/commands/info.rs

@@ -1,21 +1,31 @@
-use clap::Args;
-use clap::ValueEnum;
-
 use crate::filesystem;
 use crate::prelude::*;
+use clap::{Args, Subcommand};
 
 #[derive(Debug, Clone, Args)]
 pub struct Input {
-    #[arg(ignore_case = true)]
+    #[clap(subcommand)]
     pub info: Info,
 }
 
-#[derive(Debug, Clone, ValueEnum)]
+#[derive(Debug, Clone, Subcommand)]
 pub enum Info {
+    /// Prints a cheatsheet example.
     CheatsExample,
-    CheatsPath,
-    ConfigPath,
+    /// Prints a configuration file example.
     ConfigExample,
+
+    /// [DEPRECATED] Prints the default cheatsheets path.
+    /// Please use `info default-cheats-path` instead.
+    CheatsPath,
+    /// [DEPRECATED] Prints the default configuration path.
+    /// Please use `info default-config-path` instead.
+    ConfigPath,
+
+    /// Prints the default cheatsheets path.
+    DefaultCheatsPath,
+    /// Prints the default configuration path.
+    DefaultConfigPath,
 }
 
 impl Runnable for Input {
@@ -23,10 +33,22 @@ impl Runnable for Input {
         let info = &self.info;
 
         match info {
-            Info::CheatsExample => println!("{}", include_str!("../../docs/cheat_example.cheat")),
+            // Here should be the example commands
+            Info::CheatsExample => {
+                println!("{}", include_str!("../../docs/examples/cheatsheet/example.cheat"))
+            }
+            Info::ConfigExample => println!(
+                "{}",
+                include_str!("../../docs/examples/configuration/config-example.yaml")
+            ),
+
+            // Here should be the old deprecated default value commands
             Info::CheatsPath => println!("{}", &filesystem::default_cheat_pathbuf()?.to_string()),
             Info::ConfigPath => println!("{}", &filesystem::default_config_pathbuf()?.to_string()),
-            Info::ConfigExample => println!("{}", include_str!("../../docs/config_file_example.yaml")),
+
+            // Here should be the default values (computed at compile time)
+            Info::DefaultCheatsPath => println!("{}", &filesystem::default_cheat_pathbuf()?.to_string()),
+            Info::DefaultConfigPath => println!("{}", &filesystem::default_config_pathbuf()?.to_string()),
         }
         Ok(())
     }

src/commands/shell.rs

@@ -13,6 +13,8 @@ impl Display for Shell {
             Self::Zsh => "zsh",
             Self::Fish => "fish",
             Self::Elvish => "elvish",
+            Self::Nushell => "nushell",
+            Self::Powershell => "powershell",
         };
 
         write!(f, "{s}")
@@ -34,6 +36,8 @@ impl Runnable for Input {
             Shell::Zsh => include_str!("../../shell/navi.plugin.zsh"),
             Shell::Fish => include_str!("../../shell/navi.plugin.fish"),
             Shell::Elvish => include_str!("../../shell/navi.plugin.elv"),
+            Shell::Nushell => include_str!("../../shell/navi.plugin.nu"),
+            Shell::Powershell => include_str!("../../shell/navi.plugin.ps1"),
         };
 
         println!("{content}");

src/common/deps.rs

@@ -0,0 +1,7 @@
+use crate::prelude::*;
+
+pub trait HasDeps {
+    fn deps(&self) -> HashSet<TypeId> {
+        HashSet::new()
+    }
+}

src/common/mod.rs

@@ -1,4 +1,5 @@
 pub mod clipboard;
+pub mod deps;
 pub mod fs;
 pub mod git;
 pub mod hash;

src/common/shell.rs

@@ -11,6 +11,8 @@ pub enum Shell {
     Zsh,
     Fish,
     Elvish,
+    Nushell,
+    Powershell,
 }
 
 #[derive(Error, Debug)]

src/common/terminal.rs

@@ -50,7 +50,7 @@ pub fn parse_ansi(ansi: &str) -> Option<style::Color> {
 }
 
 #[derive(Debug, Clone)]
-pub struct Color(pub style::Color);
+pub struct Color(#[allow(unused)] pub style::Color); // suppress warning: field `0` is never read.
 
 impl FromStr for Color {
     type Err = &'static str;

src/config/mod.rs

@@ -4,6 +4,7 @@ mod yaml;
 
 use crate::commands::func::Func;
 use crate::finder::FinderChoice;
+use crate::prelude::debug;
 pub use cli::*;
 use crossterm::style::Color;
 use env::EnvConfig;
@@ -61,19 +62,45 @@ impl Config {
     }
 
     pub fn path(&self) -> Option<String> {
+        if self.clap.path.is_some() {
+            debug!("CLAP PATH: {}", self.clap.path.as_ref().unwrap());
+        }
+
         self.clap
             .path
             .clone()
-            .or_else(|| self.env.path.clone())
+            .or_else(|| {
+                if self.env.path.is_some() {
+                    debug!("ENV PATH: {}", self.env.path.as_ref().unwrap());
+                }
+
+                self.env.path.clone()
+            })
             .or_else(|| {
                 let p = self.yaml.cheats.paths.clone();
+
                 if p.is_empty() {
                     None
                 } else {
+                    debug!("MULTIPLE YAML PATH: {}", p.as_slice().join(","));
                     Some(p.join(crate::filesystem::JOIN_SEPARATOR))
                 }
             })
-            .or_else(|| self.yaml.cheats.path.clone())
+            .or_else(|| {
+                if self.yaml.cheats.path.is_some() {
+                    debug!(
+                        "DEPRECATED UNIQUE YAML PATH: {}",
+                        self.yaml.cheats.path.as_ref().unwrap()
+                    );
+                }
+
+                self.yaml.cheats.path.clone()
+            })
+            .or_else(|| {
+                debug!("No specific path given!");
+
+                None
+            })
     }
 
     pub fn finder(&self) -> FinderChoice {
@@ -99,6 +126,14 @@ impl Config {
             .or_else(|| self.yaml.finder.overrides_var.clone())
     }
 
+    pub fn delimiter_var(&self) -> Option<String> {
+        self.yaml.finder.delimiter_var.clone()
+    }
+
+    pub fn tealdeer(&self) -> bool {
+        self.yaml.client.tealdeer
+    }
+
     pub fn shell(&self) -> String {
         self.yaml.shell.command.clone()
     }
@@ -188,3 +223,9 @@ impl Config {
         }
     }
 }
+
+impl Default for Config {
+    fn default() -> Self {
+        Self::new()
+    }
+}

src/config/yaml.rs

@@ -47,6 +47,7 @@ pub struct Finder {
     pub command: FinderChoice,
     pub overrides: Option<String>,
     pub overrides_var: Option<String>,
+    pub delimiter_var: Option<String>,
 }
 
 fn finder_deserialize<'de, D>(deserializer: D) -> Result<FinderChoice, D::Error>
@@ -78,7 +79,14 @@ pub struct Shell {
     pub finder_command: Option<String>,
 }
 
-#[derive(Deserialize, Default, Debug)]
+#[derive(Deserialize, Debug)]
+#[serde(default)]
+#[derive(Default)]
+pub struct Client {
+    pub tealdeer: bool,
+}
+
+#[derive(Deserialize, Debug)]
 #[serde(default)]
 pub struct YamlConfig {
     pub style: Style,
@@ -86,6 +94,8 @@ pub struct YamlConfig {
     pub cheats: Cheats,
     pub search: Search,
     pub shell: Shell,
+    pub client: Client,
+    pub source: String, // <= The source of the current configuration
 }
 
 impl YamlConfig {
@@ -99,19 +109,36 @@ impl YamlConfig {
         serde_yaml::from_reader(reader).map_err(|e| e.into())
     }
 
-    pub fn get(env: &EnvConfig) -> Result<Self> {
+    pub fn get(env: &EnvConfig) -> Result<YamlConfig> {
         if let Some(yaml) = env.config_yaml.as_ref() {
-            return Self::from_str(yaml);
+            // We're getting the configuration from the environment variable `NAVI_CONFIG_YAML`
+            let mut cfg = Self::from_str(yaml)?;
+            cfg.source = "ENV_NAVI_CONFIG_YAML".to_string();
+
+            return Ok(cfg);
         }
         if let Some(path_str) = env.config_path.as_ref() {
+            // We're getting the configuration from a file given in the environment variable 'NAVI_CONFIG'
+
             let p = PathBuf::from(path_str);
-            return YamlConfig::from_path(&p);
+            let mut cfg = YamlConfig::from_path(&p)?;
+            cfg.source = "ENV_NAVI_CONFIG".to_string();
+
+            return Ok(cfg);
         }
         if let Ok(p) = default_config_pathbuf() {
+            // We're getting the configuration from the default path
+
             if p.exists() {
-                return YamlConfig::from_path(&p);
+                let mut cfg = YamlConfig::from_path(&p)?;
+                cfg.source = "DEFAULT_CONFIG_FILE".to_string();
+
+                return Ok(cfg);
             }
         }
+
+        // As no configuration has been found, we set the YAML configuration
+        // to be its default (built-in) value.
         Ok(YamlConfig::default())
     }
 }
@@ -150,6 +177,7 @@ impl Default for Finder {
             command: FinderChoice::Fzf,
             overrides: None,
             overrides_var: None,
+            delimiter_var: None,
         }
     }
 }
@@ -162,3 +190,17 @@ impl Default for Shell {
         }
     }
 }
+
+impl Default for YamlConfig {
+    fn default() -> Self {
+        Self {
+            style: Default::default(),
+            finder: Default::default(),
+            cheats: Default::default(),
+            search: Default::default(),
+            shell: Default::default(),
+            client: Default::default(),
+            source: "BUILT-IN".to_string(),
+        }
+    }
+}

src/filesystem.rs

@@ -1,4 +1,4 @@
-pub use crate::common::fs::{create_dir, exe_string, read_lines, remove_dir, InvalidPath, UnreadableDir};
+pub use crate::common::fs::{create_dir, exe_string, read_lines, remove_dir};
 use crate::env_var;
 use crate::parser::Parser;
 use crate::prelude::*;
@@ -53,23 +53,12 @@ fn compiled_default_path(path: Option<&str>) -> Option<PathBuf> {
 }
 
 pub fn default_cheat_pathbuf() -> Result<PathBuf> {
-    if cfg!(target_os = "macos") {
-        let base_dirs = etcetera::base_strategy::Apple::new()?;
+    let mut pathbuf = get_data_dir_by_platform()?;
 
-        let mut pathbuf = base_dirs.data_dir();
-        pathbuf.push("navi");
-        pathbuf.push("cheats");
-        if pathbuf.exists() {
-            return Ok(pathbuf);
-        }
-    }
-
-    let base_dirs = etcetera::choose_base_strategy()?;
-
-    let mut pathbuf = base_dirs.data_dir();
     pathbuf.push("navi");
     pathbuf.push("cheats");
-    if !pathbuf.exists() {
+
+    if pathbuf.exists() {
         if let Some(path) = compiled_default_path(option_env!("NAVI_PATH")) {
             pathbuf = path;
         }
@@ -78,22 +67,11 @@ pub fn default_cheat_pathbuf() -> Result<PathBuf> {
 }
 
 pub fn default_config_pathbuf() -> Result<PathBuf> {
-    if cfg!(target_os = "macos") {
-        let base_dirs = etcetera::base_strategy::Apple::new()?;
+    let mut pathbuf = get_config_dir_by_platform()?;
 
-        let mut pathbuf = base_dirs.config_dir();
-        pathbuf.push("navi");
-        pathbuf.push("config.yaml");
-        if pathbuf.exists() {
-            return Ok(pathbuf);
-        }
-    }
-
-    let base_dirs = etcetera::choose_base_strategy()?;
-
-    let mut pathbuf = base_dirs.config_dir();
     pathbuf.push("navi");
     pathbuf.push("config.yaml");
+
     if !pathbuf.exists() {
         if let Some(path) = compiled_default_path(option_env!("NAVI_CONFIG")) {
             pathbuf = path;
@@ -110,6 +88,42 @@ pub fn cheat_paths(path: Option<String>) -> Result<String> {
     }
 }
 
+////////////////////////////////////////////////////////////////////////////////////////////////////
+//
+// Here are other functions, unrelated to CLI commands (or at least not directly related)
+//
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+/// Returns the data dir computed for each platform.
+///
+/// We are currently handling two cases: When the platform is `macOS` and when the platform isn't (including `Windows` and `Linux/Unix` platforms)
+fn get_data_dir_by_platform() -> Result<PathBuf> {
+    if cfg!(target_os = "macos") {
+        let base_dirs = etcetera::base_strategy::Apple::new()?;
+
+        Ok(base_dirs.data_dir())
+    } else {
+        let base_dirs = etcetera::choose_base_strategy()?;
+
+        Ok(base_dirs.data_dir())
+    }
+}
+
+/// Returns the config dir computed for each platform.
+///
+/// We are currently handling two cases: When the platform is `macOS` and when the platform isn't (including `Windows` and `Linux/Unix` platforms)
+fn get_config_dir_by_platform() -> Result<PathBuf> {
+    if cfg!(target_os = "macos") {
+        let base_dirs = etcetera::base_strategy::Apple::new()?;
+
+        Ok(base_dirs.config_dir())
+    } else {
+        let base_dirs = etcetera::choose_base_strategy()?;
+
+        Ok(base_dirs.config_dir())
+    }
+}
+
 pub fn tmp_pathbuf() -> Result<PathBuf> {
     let mut root = default_cheat_pathbuf()?;
     root.push("tmp");

src/finder/mod.rs

@@ -9,6 +9,10 @@ pub use post::process;
 use structures::Opts;
 use structures::SuggestionType;
 
+const MIN_FZF_VERSION_MAJOR: u32 = 0;
+const MIN_FZF_VERSION_MINOR: u32 = 23;
+const MIN_FZF_VERSION_PATCH: u32 = 1;
+
 mod post;
 
 #[derive(Debug, Clone, Copy, Deserialize, ValueEnum)]
@@ -47,6 +51,20 @@ fn parse(out: Output, opts: Opts) -> Result<String> {
 }
 
 impl FinderChoice {
+    fn check_fzf_version() -> Option<(u32, u32, u32)> {
+        let output = Command::new("fzf").arg("--version").output().ok()?.stdout;
+        let version_string = String::from_utf8(output).ok()?;
+        let version_parts: Vec<_> = version_string.split('.').collect();
+        if version_parts.len() == 3 {
+            let major = version_parts[0].parse().ok()?;
+            let minor = version_parts[1].parse().ok()?;
+            let patch = version_parts[2].split_whitespace().next()?.parse().ok()?;
+            Some((major, minor, patch))
+        } else {
+            None
+        }
+    }
+
     pub fn call<F, R>(&self, finder_opts: Opts, stdin_fn: F) -> Result<(String, R)>
     where
         F: Fn(&mut dyn Write) -> Result<R>,
@@ -56,6 +74,23 @@ impl FinderChoice {
             Self::Skim => "sk",
         };
 
+        if let Self::Fzf = self {
+            if let Some((major, minor, patch)) = Self::check_fzf_version() {
+                if major == MIN_FZF_VERSION_MAJOR
+                    && minor < MIN_FZF_VERSION_MINOR
+                    && patch < MIN_FZF_VERSION_PATCH
+                {
+                    eprintln!(
+                        "Warning: Fzf version {major}.{minor} does not support the preview window layout used by navi.",
+                    );
+                    eprintln!(
+                        "Consider updating Fzf to a version >= {MIN_FZF_VERSION_MAJOR}.{MIN_FZF_VERSION_MINOR}.{MIN_FZF_VERSION_PATCH} or use a compatible layout.",
+                    );
+                    process::exit(1);
+                }
+            }
+        }
+
         let mut command = Command::new(finder_str);
         let opts = finder_opts.clone();
 

src/finder/structures.rs

@@ -66,6 +66,7 @@ impl Opts {
             overrides: CONFIG.fzf_overrides_var(),
             suggestion_type: SuggestionType::SingleRecommendation,
             prevent_select1: false,
+            delimiter: CONFIG.delimiter_var(),
             ..Default::default()
         }
     }

src/lib.rs

@@ -10,8 +10,12 @@ mod env_var;
 mod filesystem;
 mod finder;
 mod parser;
-mod prelude;
+pub mod prelude;
 mod structures;
 mod welcome;
 
+mod libs {
+    pub mod dns_common;
+}
+
 pub use {commands::handle, filesystem::default_config_pathbuf};

src/libs/dns_common/component.rs

@@ -0,0 +1,8 @@
+use crate::prelude::*;
+
+pub trait Component: Any + AsAny + Send + Sync {}
+
+pub trait AsAny: Any {
+    fn as_any(&self) -> &dyn Any;
+    fn as_mut_any(&mut self) -> &mut dyn Any;
+}

src/libs/dns_common/mod.rs

@@ -0,0 +1,2 @@
+pub mod component;
+mod tracing;

src/libs/dns_common/tracing.rs

@@ -0,0 +1,8 @@
+use crate::prelude::*;
+
+#[derive(Deserialize, Serialize, Debug, Clone)]
+#[serde(deny_unknown_fields)]
+pub struct TracingConfig {
+    pub time: bool,
+    pub level: String,
+}

src/parser.rs

@@ -225,10 +225,9 @@ impl<'a> Parser<'a> {
 
         let write_fn = self.write_fn;
 
-        return self
-            .writer
+        self.writer
             .write_all(write_fn(item).as_bytes())
-            .context("Failed to write command to finder's stdin");
+            .context("Failed to write command to finder's stdin")
     }
 
     pub fn read_lines(
@@ -254,7 +253,8 @@ impl<'a> Parser<'a> {
             }
 
             // duplicate
-            if !item.tags.is_empty() && !item.comment.is_empty() {}
+            // if !item.tags.is_empty() && !item.comment.is_empty() {}
+
             // blank
             if line.is_empty() {
                 if !item.snippet.is_empty() {

src/prelude.rs

@@ -1,9 +1,42 @@
+pub use crate::common::deps::HasDeps;
+pub use crate::common::fs::ToStringExt;
 pub use crate::config::CONFIG; // TODO
-pub use dns_common::prelude::*;
+pub use crate::libs::dns_common;
+pub use anyhow::{anyhow, Context, Error, Result};
 pub use regex::Regex;
+pub use serde::de::Deserializer;
+pub use serde::ser::Serializer;
+pub use serde::{Deserialize, Serialize};
+pub use std::any::{Any, TypeId};
+pub use std::collections::{HashMap, HashSet};
+pub use std::convert::{TryFrom, TryInto};
+pub use std::fs::File;
 pub use std::io::{BufRead, BufReader};
+pub use std::path::{Path, PathBuf};
 pub use std::process::Stdio;
 pub use std::str::FromStr;
+pub use std::sync::{Arc, Mutex, RwLock};
+pub use tracing::{self, debug, error, event, info, instrument, span, subscriber, trace, warn};
+
+pub trait Component: Any + AsAny + Send + Sync {}
+
+pub trait AsAny: Any {
+    fn as_any(&self) -> &dyn Any;
+    fn as_mut_any(&mut self) -> &mut dyn Any;
+}
+
+impl<T> AsAny for T
+where
+    T: Any,
+{
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn as_mut_any(&mut self) -> &mut dyn Any {
+        self
+    }
+}
 
 pub trait Runnable {
     fn run(&self) -> Result<()>;

src/structures/item.rs

@@ -18,6 +18,11 @@ impl Item {
     }
 
     pub fn hash(&self) -> u64 {
-        fnv(&format!("{}{}", &self.tags.trim(), &self.comment.trim()))
+        fnv(&format!(
+            "{}{}{}",
+            &self.tags.trim(),
+            &self.comment.trim(),
+            &self.snippet.trim()
+        ))
     }
 }

src/welcome.rs

@@ -3,7 +3,7 @@ use crate::prelude::*;
 use crate::structures::fetcher;
 
 pub fn populate_cheatsheet(parser: &mut Parser) -> Result<()> {
-    let cheatsheet = include_str!("../docs/navi.cheat");
+    let cheatsheet = include_str!("../docs/examples/cheatsheet/navi.cheat");
     let lines = cheatsheet.split('\n').map(|s| Ok(s.to_string()));
 
     parser.read_lines(lines, "welcome", None)?;

tests/run

@@ -159,6 +159,7 @@ test::run "bash" _navi_widget "bash"
 test::run "zsh" _navi_widget "zsh"
 test::run "fish" _navi_widget "fish"
 test::run "elvish" _navi_widget "elvish"
+test::run "nu" _navi_widget "nushell"
 
 test::set_suite "3rd party"
 test::run "tldr" _navi_tldr