diff --git a/CHANGES b/CHANGES
index 4c7b28d755..29f4b10b4a 100644
--- a/CHANGES
+++ b/CHANGES
@@ -19,6 +19,12 @@ $ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force
 
 - _Insert changes/features/fixes for next release here_
 
+## tmuxp 1.10.1 (2022-04-17)
+
+### Compatibility
+
+- {issue}`#773` (backport): Allow click 8.1.x
+
 ## tmuxp 1.10.0 (2022-03-19)
 
 ### Compatibility
diff --git a/docs/configuration/environmental-variables.md b/docs/configuration/environmental-variables.md
new file mode 100644
index 0000000000..29dc84d8f2
--- /dev/null
+++ b/docs/configuration/environmental-variables.md
@@ -0,0 +1,22 @@
+(environmental-variables)=
+
+# Environmental variables
+
+## `TMUXP_CONFIGDIR`
+
+Example: `TMUXP_CONFIGDIR=$HOME/.mytmuxpconfigdir tmuxp load cpython`
+
+## `LIBTMUX_TMUX_FORMAT_SEPARATOR`
+
+:::{seealso}
+
+[`LIBTMUX_TMUX_FORMAT_SEPARATOR`](https://libtmux.git-pull.com/api.html#tmux-format-separator) in libtmux API.
+
+:::
+
+In rare circumstances the `tmux -F` separator under the hood may cause issues
+building sessions. For this case you can override it here.
+
+```console
+$ env LIBTMUX_TMUX_FORMAT_SEPARATOR='__SEP__' tmuxp load [session]
+```
diff --git a/docs/examples.md b/docs/configuration/examples.md
similarity index 83%
rename from docs/examples.md
rename to docs/configuration/examples.md
index 262adaa734..90340cb0d8 100644
--- a/docs/examples.md
+++ b/docs/configuration/examples.md
@@ -1,6 +1,6 @@
 (examples)=
 
-# Example Configurations
+# Examples
 
 ## Short hand / inline style
 
@@ -29,7 +29,7 @@ punctual.
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/shorthands.yaml
+```{literalinclude} ../../examples/shorthands.yaml
 :language: yaml
 
 ```
@@ -39,7 +39,7 @@ punctual.
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/shorthands.json
+```{literalinclude} ../../examples/shorthands.json
 :language: json
 
 ```
@@ -55,7 +55,7 @@ Note `''` counts as an empty carriage return.
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/blank-panes.yaml
+```{literalinclude} ../../examples/blank-panes.yaml
 :language: yaml
 
 ```
@@ -64,7 +64,7 @@ Note `''` counts as an empty carriage return.
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/blank-panes.json
+```{literalinclude} ../../examples/blank-panes.json
 :language: json
 
 ```
@@ -93,7 +93,7 @@ Note `''` counts as an empty carriage return.
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/2-pane-vertical.yaml
+```{literalinclude} ../../examples/2-pane-vertical.yaml
 :language: yaml
 
 ```
@@ -102,7 +102,7 @@ Note `''` counts as an empty carriage return.
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/2-pane-vertical.json
+```{literalinclude} ../../examples/2-pane-vertical.json
 :language: json
 
 ```
@@ -131,7 +131,7 @@ Note `''` counts as an empty carriage return.
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/3-pane.yaml
+```{literalinclude} ../../examples/3-pane.yaml
 :language: yaml
 
 ```
@@ -140,7 +140,7 @@ Note `''` counts as an empty carriage return.
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/3-pane.json
+```{literalinclude} ../../examples/3-pane.json
 :language: json
 
 ```
@@ -169,7 +169,7 @@ Note `''` counts as an empty carriage return.
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/4-pane.yaml
+```{literalinclude} ../../examples/4-pane.yaml
 :language: yaml
 
 ```
@@ -178,7 +178,7 @@ Note `''` counts as an empty carriage return.
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/4-pane.json
+```{literalinclude} ../../examples/4-pane.json
 :language: json
 
 ```
@@ -191,7 +191,7 @@ Equivalent to `tmux new-window -c <start-directory>`.
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/start-directory.yaml
+```{literalinclude} ../../examples/start-directory.yaml
 :language: yaml
 
 ```
@@ -200,7 +200,7 @@ Equivalent to `tmux new-window -c <start-directory>`.
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/start-directory.json
+```{literalinclude} ../../examples/start-directory.json
 :language: json
 
 ```
@@ -244,7 +244,7 @@ please make a ticket on the [issue tracker][issue tracker].
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/env-variables.yaml
+```{literalinclude} ../../examples/env-variables.yaml
 :language: yaml
 
 ```
@@ -253,7 +253,7 @@ please make a ticket on the [issue tracker][issue tracker].
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/env-variables.json
+```{literalinclude} ../../examples/env-variables.json
 :language: json
 
 ```
@@ -266,7 +266,7 @@ tmuxp will set session environment variables.
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/session-environment.yaml
+```{literalinclude} ../../examples/session-environment.yaml
 :language: yaml
 
 ```
@@ -274,7 +274,7 @@ tmuxp will set session environment variables.
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/session-environment.json
+```{literalinclude} ../../examples/session-environment.json
 :language: json
 
 ```
@@ -288,7 +288,7 @@ selected upon loading.
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/focus-window-and-panes.yaml
+```{literalinclude} ../../examples/focus-window-and-panes.yaml
 :language: yaml
 
 ```
@@ -297,7 +297,7 @@ selected upon loading.
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/focus-window-and-panes.json
+```{literalinclude} ../../examples/focus-window-and-panes.json
 :language: json
 
 ```
@@ -312,7 +312,7 @@ This will add the `shell_command` to the bash history in the pane.
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/suppress-history.yaml
+```{literalinclude} ../../examples/suppress-history.yaml
 :language: yaml
 
 ```
@@ -321,7 +321,7 @@ This will add the `shell_command` to the bash history in the pane.
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/suppress-history.json
+```{literalinclude} ../../examples/suppress-history.json
 :language: json
 
 ```
@@ -349,7 +349,7 @@ Omit sending {kbd}`enter` to key commands. Equivalent to
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/skip-send.yaml
+```{literalinclude} ../../examples/skip-send.yaml
 :language: yaml
 
 ```
@@ -358,7 +358,7 @@ Omit sending {kbd}`enter` to key commands. Equivalent to
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/skip-send.json
+```{literalinclude} ../../examples/skip-send.json
 :language: json
 
 ```
@@ -367,7 +367,7 @@ Omit sending {kbd}`enter` to key commands. Equivalent to
 
 ````{tab} YAML (pane-level)
 
-```{literalinclude} ../examples/skip-send-pane-level.yaml
+```{literalinclude} ../../examples/skip-send-pane-level.yaml
 :language: yaml
 
 ```
@@ -376,7 +376,7 @@ Omit sending {kbd}`enter` to key commands. Equivalent to
 
 ````{tab} JSON (pane-level)
 
-```{literalinclude} ../examples/skip-send-pane-level.json
+```{literalinclude} ../../examples/skip-send-pane-level.json
 :language: json
 
 ```
@@ -408,7 +408,7 @@ This is especially useful for expensive commands where the terminal needs some b
 
 ````{tab} Virtualenv
 
-```{literalinclude} ../examples/sleep-virtualenv.yaml
+```{literalinclude} ../../examples/sleep-virtualenv.yaml
 :language: yaml
 
 ```
@@ -416,7 +416,7 @@ This is especially useful for expensive commands where the terminal needs some b
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/sleep.yaml
+```{literalinclude} ../../examples/sleep.yaml
 :language: yaml
 
 ```
@@ -425,7 +425,7 @@ This is especially useful for expensive commands where the terminal needs some b
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/sleep.json
+```{literalinclude} ../../examples/sleep.json
 :language: json
 
 ```
@@ -434,7 +434,7 @@ This is especially useful for expensive commands where the terminal needs some b
 
 ````{tab} YAML (pane-level)
 
-```{literalinclude} ../examples/sleep-pane-level.yaml
+```{literalinclude} ../../examples/sleep-pane-level.yaml
 :language: yaml
 
 ```
@@ -443,7 +443,7 @@ This is especially useful for expensive commands where the terminal needs some b
 
 ````{tab} JSON (pane-level)
 
-```{literalinclude} ../examples/sleep-pane-level.json
+```{literalinclude} ../../examples/sleep-pane-level.json
 :language: json
 
 ```
@@ -457,7 +457,7 @@ without `window_index` will use the lowest available window index.
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/window-index.yaml
+```{literalinclude} ../../examples/window-index.yaml
 :language: yaml
 
 ```
@@ -466,7 +466,7 @@ without `window_index` will use the lowest available window index.
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/window-index.json
+```{literalinclude} ../../examples/window-index.json
 :language: json
 
 ```
@@ -481,7 +481,7 @@ different shells on different panes.
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/pane-shell.yaml
+```{literalinclude} ../../examples/pane-shell.yaml
 :language: yaml
 
 ```
@@ -490,7 +490,7 @@ different shells on different panes.
 
 ````{tab} JSON
 
-```{literalinclude} ../examples/pane-shell.json
+```{literalinclude} ../../examples/pane-shell.json
 :language: json
 
 ```
@@ -507,14 +507,14 @@ Including `automatic-rename`, `default-shell`,
 
 ````{tab} YAML
 
-```{literalinclude} ../examples/options.yaml
+```{literalinclude} ../../examples/options.yaml
 :language: yaml
 
 ```
 ````
 
 ````{tab} JSON
-```{literalinclude} ../examples/options.json
+```{literalinclude} ../../examples/options.json
 :language: json
 
 ```
@@ -527,14 +527,14 @@ Apply window options after panes have been created. Useful for
 pane during creation.
 
 ````{tab} YAML
-```{literalinclude} ../examples/2-pane-synchronized.yaml
+```{literalinclude} ../../examples/2-pane-synchronized.yaml
 :language: yaml
 
 ```
 ````
 
 ````{tab} JSON
-```{literalinclude} ../examples/2-pane-synchronized.json
+```{literalinclude} ../../examples/2-pane-synchronized.json
 :language: json
 
 ```
@@ -543,14 +543,14 @@ pane during creation.
 ## Main pane height
 
 ````{tab} YAML
-```{literalinclude} ../examples/main-pane-height.yaml
+```{literalinclude} ../../examples/main-pane-height.yaml
 :language: yaml
 
 ```
 ````
 
 ````{tab} JSON
-```{literalinclude} ../examples/main-pane-height.json
+```{literalinclude} ../../examples/main-pane-height.json
 :language: json
 
 ```
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
new file mode 100644
index 0000000000..dea60190d9
--- /dev/null
+++ b/docs/configuration/index.md
@@ -0,0 +1,66 @@
+(config)=
+
+(configuration)=
+
+# Configuration
+
+The configuration syntax is declarative and based on tmux's Session, Window and
+Panes hierarchy. Both JSON and YAML is accepted.
+
+## Launching your session
+
+When you have `tmuxp` installed in your environment alongside tmux, you can use:
+
+```console
+$ tmuxp load ./path/to/file
+```
+
+to load your workspace and launch directly into tmux.
+
+In certain cases, tmuxp will try help you when:
+
+- _If your session already exists_: tmuxp will prompt you to re-attach. It does this
+  by checking if the configuration's `session_name` matches a session already
+  running on the same server.
+- _If you're inside a tmux client already_, `tmuxp` will let you create a new session and switch to it, or append the windows to your existing
+  session.
+
+## What's in a config?
+
+1. A session name: `session_name: your session`
+2. A list of _windows_
+3. A list of _panes_ for each window
+4. A list of _commands_ for each pane
+
+````{tab} Basics
+
+```yaml
+session_name: My session
+windows:
+- window_name: Window 1
+  panes:
+  - echo "pane 1"
+  - echo "pane 2"
+```
+
+````
+
+````{tab} Smallest possible
+
+```{literalinclude} ../../examples/minimal.yaml
+:language: yaml
+
+```
+
+As of 1.11.x.
+
+````
+
+## Reference and usage
+
+```{toctree}
+
+environmental-variables
+examples
+
+```
diff --git a/docs/developing.md b/docs/developing.md
index 76f3f846cd..fdfba36f10 100644
--- a/docs/developing.md
+++ b/docs/developing.md
@@ -255,6 +255,13 @@ this will load the `.tmuxp.yaml` in the root of the project.
 
 ```
 
+`.tmuxp-before-script.sh` ran by `before_script`:
+
+```{literalinclude} ../.tmuxp-before-script.sh
+:language: console
+
+```
+
 (gh-actions)=
 
 ## Github Actions
diff --git a/docs/index.md b/docs/index.md
index cf2b5781fb..a5b75c43bc 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -21,9 +21,9 @@
 
 about
 quickstart
-examples
 commands/index
-plugin_system
+configuration/index
+plugins/index
 
 ```
 
diff --git a/docs/plugin_system.md b/docs/plugins/index.md
similarity index 99%
rename from docs/plugin_system.md
rename to docs/plugins/index.md
index 6552efc597..92ce67a500 100644
--- a/docs/plugin_system.md
+++ b/docs/plugins/index.md
@@ -1,6 +1,6 @@
-(plugin-system)=
+(plugins)=
 
-# Plugin System
+# Plugins
 
 The plugin system allows users to customize and extend different aspects of
 tmuxp without the need to change tmuxp itself.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index c3395084b0..bae73b6d99 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -110,7 +110,7 @@ session. You can also load a configuration, and append the windows to
 the current active session.
 
 You can also have a custom tmuxp config directory by setting the
-`TMUX_CONFIGDIR` in your environment variables.
+`TMUXP_CONFIGDIR` in your environment variables.
 
 ```console
 
@@ -132,8 +132,7 @@ You can also [Import][import] configs [teamocil][teamocil] and [tmuxinator][tmux
 
 :::{seealso}
 
-{ref}`libtmux python API documentation <libtmux:api>` and {ref}`developing`,
-{ref}`internals`.
+{ref}`libtmux python API documentation <libtmux:api>` and {ref}`developing`.
 
 :::
 
diff --git a/docs/redirects.txt b/docs/redirects.txt
index 36313d1a38..a8d8f8af56 100644
--- a/docs/redirects.txt
+++ b/docs/redirects.txt
@@ -1 +1,3 @@
 "cli.md" "commands/index.md"
+"examples.md" "configuration/examples.md"
+"plugin_system.md" "plugins/index.md"
diff --git a/examples/minimal.yaml b/examples/minimal.yaml
new file mode 100644
index 0000000000..0efa773049
--- /dev/null
+++ b/examples/minimal.yaml
@@ -0,0 +1,4 @@
+session_name: My tmux session
+windows:
+  - panes:
+    -
diff --git a/poetry.lock b/poetry.lock
index d014220052..e2512b69dd 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -158,11 +158,11 @@ clikit = ">=0.6.0,<0.7.0"
 
 [[package]]
 name = "click"
-version = "8.0.4"
+version = "8.1.2"
 description = "Composable command line interface toolkit"
 category = "main"
 optional = false
-python-versions = ">=3.6"
+python-versions = ">=3.7"
 
 [package.dependencies]
 colorama = {version = "*", markers = "platform_system == \"Windows\""}
@@ -1285,7 +1285,7 @@ test = []
 [metadata]
 lock-version = "1.1"
 python-versions = "^3.7"
-content-hash = "301084095b8b593af4d0924c66952293d05f9dbdb7babda954a5c7344d50b3b6"
+content-hash = "fb49055dc8fbc670c8ef958461a851de697cc2ada8d17da1e30e6574264db637"
 
 [metadata.files]
 aafigure = [
@@ -1410,8 +1410,8 @@ cleo = [
     {file = "cleo-0.8.1.tar.gz", hash = "sha256:3d0e22d30117851b45970b6c14aca4ab0b18b1b53c8af57bed13208147e4069f"},
 ]
 click = [
-    {file = "click-8.0.4-py3-none-any.whl", hash = "sha256:6a7a62563bbfabfda3a38f3023a1db4a35978c0abd76f6c9605ecd6554d6d9b1"},
-    {file = "click-8.0.4.tar.gz", hash = "sha256:8458d7b1287c5fb128c90e23381cf99dcde74beaf6c7ff6384ce84d6fe090adb"},
+    {file = "click-8.1.2-py3-none-any.whl", hash = "sha256:24e1a4a9ec5bf6299411369b208c1df2188d9eb8d916302fe6bf03faed227f1e"},
+    {file = "click-8.1.2.tar.gz", hash = "sha256:479707fe14d9ec9a0757618b7a100a0ae4c4e236fac5b7f80ca68028141a1a72"},
 ]
 clikit = [
     {file = "clikit-0.6.2-py2.py3-none-any.whl", hash = "sha256:71268e074e68082306e23d7369a7b99f824a0ef926e55ba2665e911f7208489e"},
diff --git a/pyproject.toml b/pyproject.toml
index 7bd28bd407..400f762195 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "tmuxp"
-version = "1.10.0"
+version = "1.10.1"
 description = "tmux session manager"
 license = "MIT"
 authors = ["Tony Narlock <tony@git-pull.com>"]
@@ -46,7 +46,7 @@ tmuxp = 'tmuxp:cli.cli'
 
 [tool.poetry.dependencies]
 python = "^3.7"
-click = ">7,<8.1"
+click = ">7,<8.2"
 kaptan = ">=0.5.10"
 libtmux = "~0.11.0"
 colorama = ">=0.3.9"
diff --git a/tmuxp/__about__.py b/tmuxp/__about__.py
index 8f87c969c5..5aeb1b9358 100644
--- a/tmuxp/__about__.py
+++ b/tmuxp/__about__.py
@@ -1,6 +1,6 @@
 __title__ = "tmuxp"
 __package_name__ = "tmuxp"
-__version__ = "1.10.0"
+__version__ = "1.10.1"
 __description__ = "tmux session manager"
 __email__ = "tony@git-pull.com"
 __author__ = "Tony Narlock"