summaryrefslogtreecommitdiffstats
path: root/website
diff options
context:
space:
mode:
Diffstat (limited to 'website')
-rw-r--r--website/README.md13
-rw-r--r--website/custom_theme/main.html4
-rw-r--r--website/custom_theme/toc.html21
-rw-r--r--website/docs/community.md36
-rw-r--r--website/docs/css/extra.css77
-rw-r--r--website/docs/documentation/configuration.md165
-rw-r--r--website/docs/documentation/installation.md50
-rw-r--r--website/docs/documentation/tricks.md39
-rw-r--r--website/docs/documentation/usage.md254
-rw-r--r--website/docs/img/20181215-edit.pngbin0 -> 35442 bytes
-rw-r--r--website/docs/img/20181215-only-folders-with-size.pngbin0 -> 42716 bytes
-rw-r--r--website/docs/img/20181215-overview.pngbin0 -> 30963 bytes
-rw-r--r--website/docs/img/20181215-search.pngbin0 -> 32583 bytes
-rw-r--r--website/docs/img/20181218-cd.pngbin0 -> 20090 bytes
-rw-r--r--website/docs/img/20190101-flags.pngbin0 -> 20870 bytes
-rw-r--r--website/docs/img/20190110-flags.pngbin0 -> 950 bytes
-rw-r--r--website/docs/img/20190110-pattern_verb.pngbin0 -> 9423 bytes
-rw-r--r--website/docs/img/20190122-dcd_rulset.pngbin0 -> 4033 bytes
-rw-r--r--website/docs/img/20190128-cd.pngbin0 -> 24637 bytes
-rw-r--r--website/docs/img/20190128-edit.pngbin0 -> 30195 bytes
-rw-r--r--website/docs/img/20190128-only-folders-with-size.pngbin0 -> 39418 bytes
-rw-r--r--website/docs/img/20190128-overview.pngbin0 -> 31472 bytes
-rw-r--r--website/docs/img/20190128-search.pngbin0 -> 33345 bytes
-rw-r--r--website/docs/img/20190205-mycnf.pngbin0 -> 31118 bytes
-rw-r--r--website/docs/img/20190212-mycnf.pngbin0 -> 28744 bytes
-rw-r--r--website/docs/img/20190217-custom-colors-help.pngbin0 -> 35463 bytes
-rw-r--r--website/docs/img/20190217-custom-colors-tree.pngbin0 -> 38191 bytes
-rw-r--r--website/docs/img/20190305-dev-sizes.pngbin0 -> 25943 bytes
-rw-r--r--website/docs/img/20190305-rm.pngbin0 -> 28841 bytes
-rw-r--r--website/docs/img/20190305-search-hel.pngbin0 -> 15230 bytes
-rw-r--r--website/docs/img/20190306-blop.pngbin0 -> 47546 bytes
-rw-r--r--website/docs/img/20190306-md-c-client.pngbin0 -> 31249 bytes
-rw-r--r--website/docs/img/20190306-md.pngbin0 -> 31207 bytes
-rw-r--r--website/docs/img/20190306-mv.pngbin0 -> 31134 bytes
-rw-r--r--website/docs/img/logo.svg72
-rw-r--r--website/docs/img/vache-blanche.svg104
-rw-r--r--website/docs/img/vache.svg173
-rw-r--r--website/docs/index.md54
-rw-r--r--website/mkdocs.yml30
39 files changed, 1092 insertions, 0 deletions
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.
+
+
diff --git a/website/docs/documentation/tricks.md b/website/docs/documentation/tricks.md
new file mode 100644
index 0000000..18d3fa3
--- /dev/null
+++ b/website/docs/documentation/tricks.md
@@ -0,0 +1,39 @@
+
+## `dcd` : Deep fuzzy cd
+
+When you want to cd to a deep directory, using `br` is fast and easy enough:
+
+* you type `br` (and `enter`)
+* you type the name of the deep folder (or part of it)
+* you check the right line is selected
+* you do `alt-enter`
+* you're done
+
+But when you frequently go to a few specific places, you may prefer a shortcut.
+
+As broot can be driven by commands, you can define this function:
+
+ # deep fuzzy cd
+ function dcd {
+ br --only-folders --cmd "$1 :c"
+ }
+
+(paste this for example in your .bashrc)
+
+This is the *"I'm feeling lucky"* of broot, you can use it to directly jump to directories you know, when you don't need the interactive search of br.
+
+Example:
+
+![dcd ruleset](../img/20190122-dcd_rulset.png)
+
+## focus a new directory but keep the current filter
+
+Similarly, `:back` keeps can be used in place of `esc` to keep the filter when going to the previous state.
+
+## Going from a fixed search to an exact one
+
+Let's assume you type `too` to search for some files. You might have got too many matches including some where the letters aren't consecutive.
+
+You may switch to an exact search by just adding `/`, which changes the fuzzy pattern to a regular expression.
+
+Or if you realize you want to match `tOo` too, then you make it case insensitive by adding an i: `too/i`.
diff --git a/website/docs/documentation/usage.md b/website/docs/documentation/usage.md
new file mode 100644
index 0000000..f4948d6
--- /dev/null
+++ b/website/docs/documentation/usage.md
@@ -0,0 +1,254 @@
+
+# Launch Broot
+
+When the installation is [complete](installation.md##installation-completion-the-br-shell-function), you may start broot with either
+
+ broot
+
+or
+
+ br
+
+If your shell is compatible, you should prefer `br` which enables some features like `cd` from broot.
+
+You can pass as argument the path you want to see, for example
+
+ br ~
+
+# Navigate
+
+## Basics
+
+When you start broot, the current directory is displayed, with some directories open and or some lines truncated, in order to fit the available height.
+
+The first line is called the root, and is currently selected.
+
+From here you may navigate using the following keys:
+
+* <kbd class=b>↓</kbd> or <kbd class=b>↑</kbd> : select the next or previous line
+* <kbd class=b>⏎</kbd> on a simple file : leave broot and open the file using xdg-open
+* <kbd class=b>⏎</kbd> on a directory : focus the directory (i.e. make it the new root)
+* <kbd>esc</kbd> gets you back to the previous state (or leave broot if there's none)
+* <kbd>alt</kbd> + <kbd class=b>⏎</kbd> on a directory : leave broot and `cd` the shell to that directory.
+* <kbd>?</kbd> brings you to the help screen
+
+## Fuzzy Patterns
+
+You would usually not just navigate this way: you'll filter the tree.
+
+This is done simply by typing a few letters.
+
+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.
+
+For example:
+
+![search hel](../img/20190305-search-hel.png)
+
+Hitting <kbd>esc</kbd> clears the current pattern.
+
+## Regular Expressions
+
+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`.
+
+## Flags
+
+Flags are displayed at the bottom right, showing the settings regarding hidden files and .gitignore rules.
+
+![flags](../img/20190101-flags.png)
+
+## Toggles
+
+Initially, broot doesn't show files whose name starts with a dot, or files declared as ignored by a `.gitignore` file. Permissions and file sizes aren't shown.
+
+This behavior is tuned with several toggles.
+
+ | name | shortcut | description
+ |-------------------|----------|--------------------------------------------------
+ | toggle_files | files | toggle showing files (or just folders)
+ | toggle_git_ignore | gi | toggle use of .gitignore
+ | toggle_hidden | h | toggle showing hidden files
+ | toggle_perm | perm | toggle showing file permissions
+ | toggle_sizes | sizes | toggle showing sizes
+ | toggle_trim_root | t | toggle removing nodes at first level too (default)
+
+To apply one, just type a space (or `:`), then the start of its shortcut, then hit <kbd class=b>⏎</kbd>.
+
+For example typing `:s` then enter will show directory sizes:
+
+![dev sizes](../img/20190305-dev-sizes.png)
+
+You may notice a scrollbar on this screenshot.
+You may sometimes want to *not* trim the first level of the tree, which is done by using the `toggle_trim_root` (and which is also automatically done when displaying sizes).
+
+## gitignore
+
+The gitignore "toggle" has 3 modes:
+
+mode | display | filtering
+-|-|-
+no | `gi:n` | .gitignore files aren't applied
+yes | `gi:y` | .gitignore rules are applied whenever they're found. If the root contains several git projects, it means different visible subtrees follow different sets of rules
+auto| `gi:a` | if the current root is a git directory or inside one, then the rules are applied. Otherwise they aren't
+
+## Quitting broot
+
+Other than executing a command leaving broot, there are several ways to quit:
+
+* if the current root is selected, just hit `enter`
+* hit <kbd>ctrl</kbd>+<kbd>Q</kbd>
+* type `:q` or ` q` then `enter`
+
+# Verbs & Command
+
+When you used a toggle, you executed a command in it simplest form: without argument and independant from the current selection.
+
+The simplest verbs are just executed by typing a space (or `:`), then its first letters, then enter.
+
+A verb can be related to the current selection. For example typing `:p` will execute the `:parent` verb, which focuses the parent of the selection (*focusing* means taking the selected directory and making it the current root).
+
+## Verbs using the selection
+
+The `rm` verb executes the standard `rm` command.
+
+It's defined by this couple (invocation, execution):
+
+ invocation = "rm"
+ execution = "/bin/rm -rf {file}"
+
+When you type a verb, the execution pattern is completed using the selection (`{file}`), the exact command is displayed in the status line:
+
+![rm](../img/20190305-rm.png)
+
+As for filters, hitting <kbd>esc</kbd> clears the command.
+
+Selection based arguments:
+
+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}`
+
+## Verbs using arguments
+
+Some commands not only use the selection but also takes one or several argument(s).
+
+For example mkdir is defined as
+
+ invocation = "mkdir {subpath}"
+ execution = "/bin/mkdir -p {directory}/{subpath}"
+
+which means that if you type `c/d`, and the file `/a/b/some_file.rs` is selected, then the created directory would be `a/b/c/d`.
+
+Example:
+
+![md](../img/20190306-md-c-client.png)
+
+In this screenshot, we didn't type `mkdir` or its start but `md`. That's because the complete definition of this verb includes this line:
+
+ shortcut = "md"
+
+!!! Note
+ The help screen lists the whole set of available verbs, including the ones coming from the configuration.
+
+## Builtins & external commands, leaving or not
+
+There are two types of verbs, differing by their *execution* pattern (which will be covered in more details in the [configuration page](configuration.md#verbs)):
+
+* buitin features, whose execution starts with `:`, apply internal functions, for example `:toggle_perm` to trigger computation and display of unix file permissions
+* external commands, whose execution implies calling an external program, for example `rm -rf {file}`
+
+A command may leave broot (for example to start a program), or not (the tree will be refreshed).
+
+## Most common Commands
+
+!!! Note
+ Remember that you may select a verb by just typing the first letters of its name or shorcut
+
+### Navigation
+
+Command | Shortcut | Usage
+-|-|-
+back| | revert to the previous state (mapped to `esc`)
+cd | | leave broot and change directory (mapped to `alt-enter`)
+focus | goto | display the selected directory (mapped to `enter`)
+help | ? | go to the help screen
+open | | open file according to OS settings (mapped to `enter` )
+parent | p | move to the parent directory
+print_path | pp | print path and leaves broot
+quit | q | quit the application
+
+### File Manipulation
+
+Command | Shortcut | Usage
+-|-|-
+mkdir | md | create a new directory, using a name you provide as argument
+mv | | move a file or directory, to a relative path you provide as argument
+rm | | remove the selected file or directory
+
+## Adding verbs
+
+You may start with the common set of verbs but you'll very quickly want to define how to edit or create files, and probably have a few personal commands.
+
+That's why should see [how to configure verbs](configuration.md#verbs).
+
+# Launch Arguments
+
+**broot** and **br** can be passed as argument the path to display.
+
+They also accept a few other arguments which you can view with `br --help`.
+
+Most of them are display toggles, which may be useful when aliasing the function but which are accessible from inside the application anyway.
+
+Some of them are a little special, though, and are explained below:
+
+## the `--outcmd` launch argument
+
+Some external commands can't be executed from a program.
+
+This is especially the case of `cd`, which isn't a program but a shell function. In order to have any useful effect, it must be called from the parent shell, the one from which broot was launched, and a shell which isn't accessible from broot.
+
+The trick to enable broot to `cd` your shell when you do `alt-enter` is the following one:
+
+* **br** is a shell function. It creates a temp file whose path it gives as argument to **broot** using `--outcmd`
+* when you do `alt-enter`, **broot** writes `cd your-selected-path` in this file, then quits
+* **br** reads the file, deletes it, then evals the command
+
+Most users have no reason to use `--outcmd` on their own, but it can still be used to write an alternative to **br** or to port it to shells which aren't currently supported.
+
+## the `--out` launch argument
+
+If you provide a path to broot with `--out`, then a few commands won't execute anything directly but will instead write the relevant path as a line in the given file.
+
+This may be used by shell functions or other programs calling broot, in a similar way to `--outcmd`, for example in conjonction with ̀ --cmd`.
+
+## the `--cmd` launch argument
+
+This argument lets you pass commands to broot. Those commands are executed exactly like any command you would type yourself in the application, a space meaning broot must wait for the end of execution.
+
+For example if you launch
+
+ br --cmd cow /
+
+Then broot is launched in the / directory and there's simply a filter typed for you.
+
+If you do
+
+ br --cmd "/^vache :p"
+
+Then broot looks for a file whose name starts with "vache" and focus its parent.
+
+If you do
+
+ br --cmd "mucca$/ :cd"
+
+then broot searches for a file whose name ends with "mucca", and `cd` to the closest directory, leaving you on the shell, in your new directory (you may not have the time to notice the broot guy was displayed).
+
+The `--cmd` argument may be the basis for many of your own shell functions or programs.
+
+!!! Note
+ Due to the way a new char cancels an in progress search, you can't pass both a search and a verb in the same command, you have to separate them with a space. That is, if you want to search for `thing` then do `:rm` on the best match (assuming you like to live dangerously), you have to do `br --cmd "thing :rm"` instead of `br --cmd "thing:rm"`.
diff --git a/website/docs/img/20181215-edit.png b/website/docs/img/20181215-edit.png
new file mode 100644
index 0000000..6a7b0ee
--- /dev/null
+++ b/website/docs/img/20181215-edit.png
Binary files differ
diff --git a/website/docs/img/20181215-only-folders-with-size.png b/website/docs/img/20181215-only-folders-with-size.png
new file mode 100644
index 0000000..41adb6c
--- /dev/null
+++ b/website/docs/img/20181215-only-folders-with-size.png
Binary files differ
diff --git a/website/docs/img/20181215-overview.png b/website/docs/img/20181215-overview.png
new file mode 100644
index 0000000..d154f3f
--- /dev/null
+++ b/website/docs/img/20181215-overview.png
Binary files differ
diff --git a/website/docs/img/20181215-search.png b/website/docs/img/20181215-search.png
new file mode 100644
index 0000000..988dbfb
--- /dev/null
+++ b/website/docs/img/20181215-search.png
Binary files differ
diff --git a/website/docs/img/20181218-cd.png b/website/docs/img/20181218-cd.png
new file mode 100644
index 0000000..493b842
--- /dev/null
+++ b/website/docs/img/20181218-cd.png
Binary files differ
diff --git a/website/docs/img/20190101-flags.png b/website/docs/img/20190101-flags.png
new file mode 100644
index 0000000..ad194fb
--- /dev/null
+++ b/website/docs/img/20190101-flags.png
Binary files differ
diff --git a/website/docs/img/20190110-flags.png b/website/docs/img/20190110-flags.png
new file mode 100644
index 0000000..74eb5fc
--- /dev/null
+++ b/website/docs/img/20190110-flags.png
Binary files differ
diff --git a/website/docs/img/20190110-pattern_verb.png b/website/docs/img/20190110-pattern_verb.png
new file mode 100644
index 0000000..df0b07d
--- /dev/null
+++ b/website/docs/img/20190110-pattern_verb.png
Binary files differ
diff --git a/website/docs/img/20190122-dcd_rulset.png b/website/docs/img/20190122-dcd_rulset.png
new file mode 100644
index 0000000..6869f72
--- /dev/null
+++ b/website/docs/img/20190122-dcd_rulset.png
Binary files differ
diff --git a/website/docs/img/20190128-cd.png b/website/docs/img/20190128-cd.png
new file mode 100644
index 0000000..6cadf86
--- /dev/null
+++ b/website/docs/img/20190128-cd.png
Binary files differ
diff --git a/website/docs/img/20190128-edit.png b/website/docs/img/20190128-edit.png
new file mode 100644
index 0000000..9ad64c7
--- /dev/null
+++ b/website/docs/img/20190128-edit.png
Binary files differ
diff --git a/website/docs/img/20190128-only-folders-with-size.png b/website/docs/img/20190128-only-folders-with-size.png
new file mode 100644
index 0000000..c5150e6
--- /dev/null
+++ b/website/docs/img/20190128-only-folders-with-size.png
Binary files differ
diff --git a/website/docs/img/20190128-overview.png b/website/docs/img/20190128-overview.png
new file mode 100644
index 0000000..ef20d1e
--- /dev/null
+++ b/website/docs/img/20190128-overview.png
Binary files differ
diff --git a/website/docs/img/20190128-search.png b/website/docs/img/20190128-search.png
new file mode 100644
index 0000000..f4b00d3
--- /dev/null
+++ b/website/docs/img/20190128-search.png
Binary files differ
diff --git a/website/docs/img/20190205-mycnf.png b/website/docs/img/20190205-mycnf.png
new file mode 100644
index 0000000..c31ab51
--- /dev/null
+++ b/website/docs/img/20190205-mycnf.png
Binary files differ
diff --git a/website/docs/img/20190212-mycnf.png b/website/docs/img/20190212-mycnf.png
new file mode 100644
index 0000000..c4ac174
--- /dev/null
+++ b/website/docs/img/20190212-mycnf.png
Binary files differ
diff --git a/website/docs/img/20190217-custom-colors-help.png b/website/docs/img/20190217-custom-colors-help.png
new file mode 100644
index 0000000..729effc
--- /dev/null
+++ b/website/docs/img/20190217-custom-colors-help.png
Binary files differ
diff --git a/website/docs/img/20190217-custom-colors-tree.png b/website/docs/img/20190217-custom-colors-tree.png
new file mode 100644
index 0000000..c09f41a
--- /dev/null
+++ b/