new documentation website

45 files changed, 1103 insertions, 302 deletions

diff --git a/.gitignore b/.gitignore
index e28e311..6d55335 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,6 @@
 bench.sh
 dev.log
 deploy.sh
-docs
 install.sh
 notes.md
 /releases
@@ -12,3 +11,5 @@ perf.data*
 off
 screens
 tests
+/website/site
+graphics
diff --git a/README.md b/README.md
index 5fd01d0..40b3f11 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,11 @@
 
 [![Build Status](https://travis-ci.org/Canop/broot.svg?branch=master)](https://travis-ci.org/Canop/broot)
 [![Chat on Miaou](https://miaou.dystroy.org/static/shields/room-en.svg?v=1)](https://miaou.dystroy.org/3490?broot)
-[![Chat on Miaou](https://miaou.dystroy.org/static/shields/room-fr.svg?v=1)](https://miaou.dystroy.org/3490?broot)
+[![Chat on Miaou](https://miaou.dystroy.org/static/shields/room-fr.svg?v=1)](https://miaou.dystroy.org/3)
 
-A better way to navigate directories.
+A better way to navigate directories
+
+[**Broot's Web Site**](https://dystroy.org/broot)
 
 ### Get an overview of a directory, even a big one:
 
@@ -58,54 +60,5 @@ Just find the file you want to edit with a few keystrokes, type `:e`, then `<ent
 
 ### More...
 
-See the complete [Documentation](documentation.md).
-
-## Installation
-
-### Compile
-
-You'll need to have the [Rust development environment](https://www.rust-lang.org/tools/install) installed.
-
-#### From crates.io
-
-    cargo install broot
-
-#### From Source
-
-Fetch the Canop/broot repository, move to the broot directory, then run
-
-    cargo build --release
-
-The executable is written in the `target/release` directory (you might want to move it to your `/usr/bin`, or to add the release directory to your path).
-
-Building from the repository, you'll get the most recent version... and the least tested one.
-
-### From up to date precompiled binaries
-
-* [x86_64-linux](https://dystroy.org/broot/x86_64-linux/broot)
-
-### Installation Completion : the `br` shell function
-
-broot is convenient to find a directory then `cd` to it, which is done using `<alt><enter>` or `:cd`.
-
-But broot needs a companion function in the shell in order to be able to change directory.
-
-To enable this feature, broot asks the permission to register this shell function on first run.
-
-When it's done, you can do just `br` to launch broot, and typing `<alt><enter>` will cd for you.
-
-## Development
-
-To make tests easier during development, a log file can be generated (and followed using `tail -f`) by using the BROOT_LOG environment variable.
-
-For example:
-
-    BROOT_LOG=debug cargo run
-
-or
-
-    BROOT_LOG=info cargo run
-
-If you want to discuss the code or features of broot, please come to [our chat](https://miaou.dystroy.org/3490?broot). Before you start coding for a PR, it would really be a good idea to come and talk about it.
+See [Broot's web site](https://dystroy.org/broot) for instructions regarding installation and usage.
 
-If you'd like a new feature, don't hesitate to ask for it.
diff --git a/documentation.md b/documentation.md
index 48c58f6..103a6ea 100644
--- a/documentation.md
+++ b/documentation.md
@@ -1,248 +1,3 @@
 
-# Broot Documentation
+Broot Docmumentation was to big to fit here and moved to [https://dystroy.org/broot](https://dystroy.org/broot).
 
-## General Usage & Semantics
-
-A broot command is typed in the input at the bottom and is made of two parts, a **pattern** and a **verb**, both optional, separated by either a space or `:`.
-
-Example:
-
-![command](img/20190110-pattern_verb.png)
-
-There the pattern is `car` and the verb shortcut is `e`.
-
-The pattern filters the tree while you type. It's interpreted in a fuzzy way so that you don't have to type all the letters or even consecutive letters. The best match is automatically selected.
-
-If there's a `/` before or after the patten, it's interpreted as a regular expression. For example `/pat+ern` would match `"patern.zip"` or `"some_patttern.rar"` but not `"pATTern"`. If you want the regex to be case insensitive, add the `i` flag: `pat+ern/i`.
-
-At any moment you can use the arrow keys to move the selection. You can also use the tab key.
-
-When you hit `<enter>`:
-
-* if there's a verb, it is executed, which may quit broot or change its state
-* if there's none, and a directory is selected, this directory becomes the new root and the pattern is cleared
-* if there's no verb and a file is selected, `xdg-open` is called on the file
-
-Hitting `<esc>` clears the current pattern, or brings you back to the previous root. If there is none, it quits broot.
-
-Hitting `?` brings you to the help screen.
-
-## Flags
-
-Flags are displayed at the bottom right, showing the settings regarding hidden files and .gitignore rules.
-
-![flags](img/20190101-flags.png)
-
-## Verbs
-
-The definition of a verb (which you'll find in the configuration file, see below) contains several parts.
-
-Two of them aren't optional:
-
-* an invocation string, defining what you type to call the function
-* the execution, defining what it does
-
-For example this one:
-
-	[[verbs]]
-	invocation = "p"
-	execution = ":parent"
-
-Or this one:
-
-	[[verbs]]
-	invocation = "create {subpath}"
-	execution = "/usr/bin/nvim {directory}/{subpath}"
-
-We see here two types of execution:
-* the first one, starting with `:`, calls a builtin function
-* the second one calls an external program (nvim)
-
-This means that typing `:create` then a name, then `<enter>` opens the selected new file in neovim (when you're in the help screen, the selected file is broot's configuration file).
-
-If you want your command to be executed from the parent shell, add this to the verb definition:
-
-	from_shell = true
-
-You may also use `{directory}` in your execution pattern: it would refer to the closest directory: either the selected file if it's a directory, or else the parent directory.
-
-When you're on the help screen, some verbs can still be applied. `{file}` is then the configuration file and `{directory}` the configuration directory.
-
-Most verbs aren't based on an external application but call internal functions:
-
-### `:back` : get back to the previous state of the tree
-
-This is normally achieved with the `esc` key but you might want to remap it.
-
-### `:cd` : cd to a directory
-
-`:cd` is the most useful verb but only works if you're using the `br` shell function to launch `broot`.
-
-If you call it on a simple file, instead of a directory, the shell will be directed to the parent directory.
-
-It's mapped to `<alt><enter>`.
-
-### `:focus` : change the tree's root
-
-`:focus` makes the selected directory become the new displayed root.
-
-The difference from just using `<enter>` is that the current filtering pattern is kept.
-
-In the default configuration, it's mapped to `g`.
-
-### `:open` : call the OS standard program for the selected file
-
-This is automatically called when you hit `<enter>` without a verb and a file (not a directory) is selected. Current implementation calls `xdg_open`.
-
-In the default configuration, it's mapped to `o`.
-
-### `:parent` : moves the view one level up
-
-Display the parent directory.
-
-In the default configuration, it's mapped to `p`.
-
-### `:quit`
-
-In the default configuration, it's mapped to `q`.
-
-### `:toggle_files`
-
-Switch between displaying only directories or showing everything.
-
-In the default configuration, it's mapped to `f`.
-
-### `:toggle_gitignore` : adjust git ignore rule respect
-
-.gitignore files are parsed and used depending on the current "gitignore" setting:
-
-* when "no", .gitignore files are ignored
-* when "yes", each directory is filtered according to the applied gitignore files (several git repositories may be simultaneously shown and a git repository may define several .gitignore files)
-* when "auto" (default value), gitignore rules are ignored unless the root directory is a git repository or inside one
-
-This setting is displayed at the bottom right of the screen:
-
-![flags](img/20190110-flags.png)
-
-In the default configuration, it's mapped to `gi`.
-
-### `:toggle_hidden`
-
-Switch between showing or hiding hidden files (the ones whose name starts with a dot).
-
-In the default configuration, it's mapped to `h`.
-
-You can start broot with hidden files shown by using `broot --hidden` or `br -h`.
-
-### `:toggle_perm` : display file permissions
-
-Toggle displaying permissions in the classical `rwxrwxrwx user group` way.
-
-In the default configuration, it's mapped to `perm`. You might want to remap it if you use it a lot.
-
-### `:toggle_sizes`
-
-Switch between displaying file & directory sizes or not.
-
-Sizes are computed in the background, so this doesn't slow your navigation.
-
-When sizes are displayed, all the direct children of the current root are displayed, which means there can be a scrollbar (you may use the page up and page down keys).
-
-In the default configuration, it's mapped to `s` and can be activated at launch using `broot --sizes`.
-
-## Configuration File
-
-When broot starts, it checks for a configuration file in the standard location defined by your OS and creates one if there's none.
-
-You can see this location by opening the help with `?`. You can also open it directly from the help screen by typing `:o`.
-
-## Passing commands as program argument
-
-*Note: this feature is experimental and will probably change.*
-
-Commands to be executed can be passed using the `--cmd` argument, separated with a space.
-
-### Directly search
-
-    broot --cmd miaou /
-
-This opens broot and immediately searches for "miaou" in `/` as if it were typed in broot's input.
-
-### Go to the most relevant directory
-
-    broot -c ":p miaou :g"
-
-This opens broot, goes to the parent directory, searches for "miaou", then opens the selected directory (staying in broot).
-
-A variant searching from your home directory:
-
-    br -f -c "miaou :g" ~
-
-### Define a function for deep fuzzy cd
-
-In my .bashrc, I have this:
-
-	# deep fuzzy cd
-	function dcd {
-		br --only-folders --cmd "$1 :c"
-	}
-
-This is the *"I'm feeling lucky"* of broot, I use it to directly jump to directories I know, when I don't need the interactive search of br.
-
-Example:
-
-![dcd ruleset](img/20190122-dcd_rulset.png)
-
-## Custom Colors
-
-You can change all colors by adding a `[skin]` section in your `conf.toml` file.
-
-For example:
-
-    [skin]
-    status_normal_fg = "grayscale(18)"
-    status_normal_bg = "grayscale(3)"
-    status_error_fg = "red"
-    status_error_bg = "yellow"
-    tree_fg = "red"
-    selected_line_bg = "grayscale(7)"
-    permissions_fg = "grayscale(12)"
-    size_bar_full_bg = "red"
-    size_bar_void_bg = "black"
-    directory_fg = "lightyellow"
-    input_fg = "cyan"
-    flag_value_fg = "lightyellow"
-    table_border_fg = "red"
-    code_fg = "lightyellow"
-
-which would look like this:
-
-![custom colors tree](img/20190217-custom-colors-tree.png)
-
-![custom colors help](img/20190217-custom-colors-help.png)
-
-Complete list of keys (expected to change before the v1 of broot):
-
-    char_match
-    code
-    directory
-    file
-    file_error
-    flag_label
-    flag_value
-    exe
-    input
-    link
-    permissions
-    selected_line
-    size_bar_full
-    size_bar_void
-    size_text
-    spinner
-    status_error
-    status_normal
-    table_border
-    tree
-    unlisted
-
-Add `_fg` for a foreground color while `_bg` is for background colors.
diff --git a/src/conf.rs b/src/conf.rs
index fd69d4d..c2c52db 100644
--- a/src/conf.rs
+++ b/src/conf.rs
@@ -174,7 +174,7 @@ const DEFAULT_CONF_FILE: &str = r#"
 # 	or one of the built-in commands.
 #
 # The configuration documentation and complete list of built-in verbs
-# can be found in https://github.com/Canop/broot/blob/master/documentation.md
+# can be found in https://github.com/Canop/broot
 
 
 ###############################
diff --git a/src/shell_bash.rs b/src/shell_bash.rs
index 6362549..f135264 100644
--- a/src/shell_bash.rs
+++ b/src/shell_bash.rs
@@ -12,7 +12,7 @@ pub const BASH: ShellFamily<'static> = ShellFamily {
 // but linked from both the .bashrc and the .zshrc files
 const BASH_FUNC: &str = r#"
 # This script was automatically generated by the broot function
-# More information can be found in https://github.com/Canop/broot/blob/master/documentation.md
+# More information can be found in https://github.com/Canop/broot
 
 # This function starts broot and executes the command
 # it produces, if any.
diff --git a/src/shell_fish.rs b/src/shell_fish.rs
index e0febc6..3b09fee 100644
--- a/src/shell_fish.rs
+++ b/src/shell_fish.rs
@@ -9,7 +9,7 @@ pub const FISH: ShellFamily<'static> = ShellFamily {
 
 const FISH_FUNC: &str = r#"
 # This script was automatically generated by the broot function
-# More information can be found in https://github.com/Canop/broot/blob/master/documentation.md
+# More information can be found in https://github.com/Canop/broot
 
 # This function starts broot and executes the command
 # it produces, if any.
diff --git a/website/README.md b/website/README.md
new file mode 100644
index 0000000..69eeaef
--- /dev/null
+++ b/website/README.md
@@ -0,0 +1,13 @@
+
+Broot's website is live at https://dystroy.org/broot
+
+It's built using [mkdocs](https://www.mkdocs.org/) (minimal version: 1.0.4).
+
+To test it locally, cd to the website directory then
+
+	mkdocs serve
+
+To build it, do
+
+	mkdocs build
+
diff --git a/website/custom_theme/main.html b/website/custom_theme/main.html
new file mode 100644
index 0000000..917a5ec
--- /dev/null
+++ b/website/custom_theme/main.html
@@ -0,0 +1,4 @@
+{% extends "base.html" %}
+
+{% block footer %}
+{% endblock %}
diff --git a/website/custom_theme/toc.html b/website/custom_theme/toc.html
new file mode 100644
index 0000000..a8576f1
--- /dev/null
+++ b/website/custom_theme/toc.html
@@ -0,0 +1,21 @@
+<div class="navbar-light navbar-expand-md bs-sidebar hidden-print affix" role="complementary">
+
+    <!--
+    <div class=logo-wrap>
+        <img src={{ "img/vache.svg"|url }}>
+    </div>
+    -->
+    <div id="toc-collapse" class="navbar-collapse collapse card bg-secondary">
+	<div class=toc-header>{{ page.title }}</div>
+        <ul class="nav flex-column bs-sidenav">
+        {%- for toc_item in page.toc %}
+            <li class="nav-item main"><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
+            {%- for toc_item in toc_item.children %}
+                <li class="nav-item">
+                    <a href="{{ toc_item.url }}" class="nav-link{% if toc_item.active %} active{% endif %}">{{ toc_item.title }}</a>
+                </li>
+            {%- endfor %}
+        {%- endfor %}
+        </ul>
+    </div>
+</div>
diff --git a/website/docs/community.md b/website/docs/community.md
new file mode 100644
index 0000000..f4a66f8
--- /dev/null
+++ b/website/docs/community.md
@@ -0,0 +1,36 @@
+
+**broot** is developped by [Denys Séguret](https://stackoverflow.com/users/263525), also known as [Canop](https://github.com/Canop) or [dystroy](https://dystroy.org).
+
+## Discuss Broot in a chat room
+
+The best place to chat about broot, to talk about features or bugs, is the Miaou chat.
+
+There's a dedicated room:
+
+[![Chat on Miaou](https://miaou.dystroy.org/static/shields/room-en.svg?v=1)](https://miaou.dystroy.org/3490?broot) **broot**
+
+If you're French speaking, you might prefer to directly come where other French speaking programmers hang:
+
+[![Chat on Miaou](https://miaou.dystroy.org/static/shields/room-fr.svg?v=1)](https://miaou.dystroy.org/3490?broot) **Code & Croissants**
+
+## Issues
+
+We use [GitHub's issue manager](https://github.com/Canop/broot/issues).
+
+Before posting a new issue, check your problem hasn't already been raised and in case of doubt please come first discuss it on the chat.
+
+## Contribute
+
+**Broot** is written in [rust](https://www.rust-lang.org/). The current focus is linux but mac should be supported in the future and maybe windows too.
+
+Before starting working on a Pull Request, please join the Miaou room to coordinate the developement. There are frequently several feature branchs waiting to be merged and adding some wild ones may make the process painful.
+
+If you think you might help, as a tester or coder, you're welcome.
+
+## This documentation...
+
+... needs your help too.
+
+Tell us what seems to be unclear or missing, what tricks should be added.
+
+And if you have interesting screenshots telling a story, they might find their way into a new page too.
diff --git a/website/docs/css/extra.css b/website/docs/css/extra.css
new file mode 100644
index 0000000..7871cf6
--- /dev/null
+++ b/website/docs/css/extra.css
@@ -0,0 +1,77 @@
+/********************/
+/* standard classes */
+
+body::before {
+	background: 0;
+}
+
+h1 {
+	font-size: 30px;
+}
+h2 {
+	font-size: 24px;
+}
+h3 {
+	font-size: 18px;
+}
+
+.navbar {
+	background-image: linear-gradient(#184965,#02121b);
+}
+
+pre {
+	padding: 0;
+	border-radius: 0;
+}
+
+kbd {
+	padding: 2px 4px;
+	color: #fff;
+	background-color: #333;
+	border-radius: 2px;
+	box-shadow: none;
+}
+
+kbd.b {
+	font-size: 18px;
+	padding: 0 5px;
+}
+
+.col-md-9 img {
+	max-width: 100%;
+	display: inline-block;
+	padding: 0;
+	line-height: 1.428571429;
+	background-color: #fff;
+	border: none;
+	border-radius: 0;
+	margin: 10px auto 20px auto;
+}
+
+.navbar-brand {
+	background: url(../img/vache-blanche.svg) no-repeat;
+	background-position: left center;
+	background-size: 40px 40px;
+	padding-left: 50px;
+}
+
+/******************/
+/* custom classes */
+
+.toc-header {
+	font-weight: bold;
+	font-size: 18px;
+	margin-left: 20px;
+	padding-bottom: 8px;
+	border-bottom: thin solid #335;
+}
+
+.logo-wrap {
+	display: flex;
+	height: 90px;
+	align-items: center;
+	justify-content: center;
+}
+.logo-wrap img {
+	width: 70px;
+}
diff --git a/website/docs/documentation/configuration.md b/website/docs/documentation/configuration.md
new file mode 100644
index 0000000..6433ac9
--- /dev/null
+++ b/website/docs/documentation/configuration.md
@@ -0,0 +1,165 @@
+
+# Opening the configuration file
+
+The configuration file location follows the XDG convention and its location depends on your OS.
+
+The easiest way to read and edit broot's configuration file is to go the help screen (using <kbd>?</kbd>) then to type `:open`.
+
+This file is called conf.toml and is in [TOML](https://github.com/toml-lang/toml).
+
+Currently, you can configure
+
+* verbs
+* colors
+
+# Verbs
+
+You can define a new verb in the TOML configuration file with a `[[verbs]]` section similar to this one:
+
+	[[verbs]]
+	invocation = "edit"
+	shortcut = "e"
+	execution = "/usr/bin/nvim {file}"
+
+## Verb Definition Attributes
+
+name | mandatory | role
+-|-|-
+invocation | yes | how the verb is called by the user, with placeholders for arguments
+execution | yes | how the verb is executed
+shorcut | no | an alternate way to call the verb (without the arguments part)
+leave_broot | no | whether to quit broot on execution (default: `true`)
+from_shell | no | whether the verb must be executed from the parent shell (needs `br`, default: `false`)
+
+### Shortcuts and Verb search
+
+**broot** looks for the first token following a space or `:` and tryes to find the verb you want.
+
+* If what you typed is exactly the shorcut or name of a verb, then this verb is selected: broot explains you what it would do if you were to type `enter`
+* If there's exactly one verb whose name or shortcut starts with the characters you typed, then it's selected
+* if there are several verbs whose name or shortcut start with the characters you typed, then broot waits for more
+* if no verb has a name or shortcut starting with those characters, broot tells you there's a problem
+
+Knowing this algorithm, you may understand the point in the following definition:
+
+	[[verbs]]
+	invocation = "p"
+	execution = ":parent"
+
+This verb is an alias to the internal builtin already available if you type `:parent`.
+
+Its interest is that if you do `:p`, then `enter`, it is executed even while there are other verbs whose invocation pattern starts with a `p`.
+
+Use shortcuts for verbs you frequently use.
+
+
+### Arguments
+
+The execution of a verb can take one or several arguments.
+
+For example it may be defined as `/usr/bin/vi {file}̀ .
+
+Some arguments are predefined in broot and depends on the current selection:
+
+name | expanded to
+-|-
+`{file}` | the complete path of the current selection
+`{parent}` | the complete path of the current selection's parent
+`{directory}` | the closest directory, either `{file}` or `{parent}`
+
+!!!	Note
+	when you're in the help screen, `{file}` is the configuration file, while `{directory}` is the configuration directory.
+
+But you may also define some arguments in the invocation pattern. For example:
+
+	[[verbs]]
+	invocation = "mkdir {subpath}"
+	execution = "/bin/mkdir -p {directory}/{subpath}"
+
+(this one has now been made standard so you don't have to write it in the configuration file)
+
+In this case the subpath is read from what you type:
+
+![md sub](../img/20190306-md.png)
+
+As you see, there's a space in this path, but it works. **broot** tries to determine when to wrap path in quotes and when to escape so that such a command correctly works.
+
+It also normalizes the paths it finds which eases the use of relative paths:
+
+![mv](../img/20190306-mv.png)
+
+Here's another example, where the invocation pattern defines two arguments by destructuring:
+
+	[[verbs]]
+	invocation = "blop {name}\\.{type}"
+	execution = "/bin/mkdir {parent}/{type} && /usr/bin/nvim {parent}/{type}/{name}.{type}"
+	from_shell = true
+
+And here's how it would look like:
+
+![blop](../img/20190306-blop.png)
+
+Notice the `\\.` ? That's because the invocation pattern is interpreted as a regular expression
+(with just a shortcut for the easy case, enabling `{name}`).
+The whole regular expression syntax may be useful for more complex rules.
+Let's say we don't want the type to contain dots, then we do this:
+
+	[[verbs]]
+	invocation = "blop {name}\\.(?P<type>[^.]+)"
+	execution = "/bin/mkdir {parent}/{type} && /usr/bin/nvim {parent}/{type}/{name}.{type}"
+	from_shell = true
+
+# Colors
+
+You can change all colors by adding a `[skin]` section in your `conf.toml` file.
+
+For example:
+
+    [skin]
+    status_normal_fg = "grayscale(18)"
+    status_normal_bg = "grayscale(3)"
+    status_error_fg = "red"
+    status_error_bg = "yellow"
+    tree_fg = "red"
+    selected_line_bg = "grayscale(7)"
+    permissions_fg = "grayscale(12)"
+    size_bar_full_bg = "red"
+    size_bar_void_bg = "black"
+    directory_fg = "lightyellow"
+    input_fg = "cyan"
+    flag_value_fg = "lightyellow"
+    table_border_fg = "red"
+    code_fg = "lightyellow"
+
+which would look like this:
+
+![custom colors tree](../img/20190217-custom-colors-tree.png)
+
+![custom colors help](../img/20190217-custom-colors-help.png)
+
+Complete list of keys (expected to change before the v1 of broot):
+
+    char_match
+    code
+    directory
+    file
+    file_error
+    flag_label
+    flag_value
+    exe
+    input
+    link
+    permissions
+    selected_line
+    size_bar_full
+    size_bar_void
+    size_text
+    spinner
+    status_error
+    status_normal
+    table_border
+    tree
+    unlisted
+
+Add `_fg` for a foreground color while `_bg` is for background colors.
+
diff --git a/website/docs/documentation/installation.md b/website/docs/documentation/installation.md
new file mode 100644
index 0000000..0302111
--- /dev/null
+++ b/website/docs/documentation/installation.md
@@ -0,0 +1,50 @@
+
+The current version of broot only runs on linux.
+
+Precompiled binaries and the crates.io repository are updated at the same time, with tested releases.
+
+If you prefer to get the very last version, even when not tagged, you may compile from the sources available on GitHub.
+
+# From precompiled binaries
+
+The last one is always made available at:
+
+* [x86_64-linux](https://dystroy.org/broot/download/x86_64-linux/broot)
+
+You may download previous releases on [GitHub releases](https://github.com/Canop/broot/releases).
+
+# From crates.io
+
+You'll need to have the [Rust development environment](https://www.rust-lang.org/tools/install) installed.
+
+Once it's installed, use cargo to install broot:
+
+    cargo install broot
+
+# From source
+
+You'll need to have the [Rust development environment](https://www.rust-lang.org/tools/install) installed.
+
+Fetch the Canop/broot repository, move to the broot directory, then run
+
+    cargo build --release
+
+The executable is written in the `target/release` directory (you might want to move it to your `/usr/bin`, or to add the release directory to your path).
+
+# Installation Completion : the `br` shell function
+
+broot is convenient to find a directory then `cd` to it, which is done using `<alt><enter>` or `:cd`.
+
+But broot needs a companion function in the shell in order to be able to change directory.
+
+When you start broot, it checks whether the `br` shell function seems to have been installed (or
+to have been refused). If needed, and if the used shell seems compatible (supported shells today are bash, zsh and fish),
+then broot asks the permission to register this shell function.
+
+If you have messed with the configuration files, you might want to have the shell function reinstalled.
+
+In order to do this, either remove all broot config files, or launch `broot --install`.
+
+When it's done, you can do just `br` to launch broot, and typing `<alt><enter>` will cd for you.