docs(configuration): More info on files

Author: tony

docs/configuration/index.md

@@ -4,13 +4,13 @@
 
 # Configuration
 
-The configuration syntax is declarative and based on tmux's Session, Window and
-Panes hierarchy. Both JSON and YAML is accepted.
+tmuxp loads your terminal workspace into tmux using config files.
+
+The configuration file can be JSON or YAML. It's declarative style resembles tmux's object hierarchy: session, window and wanes.
 
 ## Launching your session
 
-When you have `tmuxp` installed in your environment alongside tmux, you can load
-a workspace with:
+Once you have `tmuxp` installed alongside tmux, you can load a workspace with:
 
 ```console
 $ tmuxp load ./path/to/file
@@ -24,7 +24,7 @@ tmuxp will offers to assist when:
 - _When inside a tmux client_, `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?
+## What's in a config file?
 
 1. A session name
 2. A list of _windows_
@@ -69,33 +69,94 @@ Breaking down the basic configuration into sections:
 
    ```yaml
    windows:
-   - window_name: Window 1
-     panes: ...
-     # window settings
-   - window_name: Window 2
-     panes: ...
-     # window settings
+     - window_name: Window 1
+       panes: ...
+       # window settings
+     - window_name: Window 2
+       panes: ...
+       # window settings
    ```
+
 3. A list of _panes_ for each window
 
    ```yaml
    windows:
      panes:
-     - # pane settings
-     - # pane settings
+       -  # pane settings
+       -  # pane settings
    ```
+
 4. A list of _commands_ for each pane
 
    ```yaml
    windows:
      panes:
-     - shell_commands:
-       - cmd: echo "pane 1 - cmd 1"
-         # command options
-       - cmd: echo "pane 1 - cmd 2"
-         # command options
+       - shell_commands:
+           - cmd: echo "pane 1 - cmd 1"
+             # command options
+           - cmd: echo "pane 1 - cmd 2"
+             # command options
    ```
 
+## Where do I store config files?
+
+### Direct
+
+You can create a configuration and load it from anywhere in your file system.
+
+```console
+$ tmuxp load [config_file]
+```
+
+````{tab} Relative
+```console
+$ tmuxp load ./favorites.yaml
+```
+````
+
+````{tab} Absolute
+```console
+$ tmuxp load /opt/myapp/favorites.yaml
+```
+````
+
+### User-based configurations
+
+tmuxp uses the [XDG Base Directory] specification.
+
+Often on POSIX machines, you will store them in `~/.config/tmuxp`.
+
+Assume you store `apple.yaml` in `$XDG_CONFIG_HOME/tmuxp/apple.yaml`, you can
+then use:
+
+```console
+$ tmuxp load apple
+```
+
+[xdg base directory]: https://specifications.freedesktop.org/basedir-spec/latest/
+
+### Project-specific
+
+You can store a configuration in your project's root directory as `.tmuxp.yaml` or `.tmuxp.json`, then:
+
+Assume `.tmuxp.yaml` inside `/opt/myapp`
+
+```console
+$ tmuxp load [config_path]
+```
+
+````{tab} In project root
+```console
+$ tmuxp load ./
+```
+````
+
+````{tab} Absolute
+```console
+$ tmuxp load /opt/myapp
+```
+````
+
 ## Reference and usage
 
 ```{toctree}