-If you experience issues with xrandr being executed too early after connecting
-a new monitor, then you can create a script `predetect`, which will be executed
-before autorandr attempts to run xrandr. Place e.g. `sleep 1` into that file
-to make autorandr wait a second before running xrandr.
+## Hook scripts
+
+Three more scripts can be placed in the configuration directory (as
+(as defined by the [XDG spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),
+usually `~/.config/autorandr` or `~/.autorandr` if you have an old installation
+for user configuration and `/etc/xdg/autorandr` for system wide configuration):
+
+- `postswitch` is executed *after* a mode switch has taken place. This can be
+ used to notify window managers or other applications about the switch.
+- `preswitch` is executed *before* a mode switch takes place.
+- `postsave` is executed after a profile was stored or altered.
+- `predetect` is executed before autorandr attempts to run xrandr.
+
+These scripts must be executable and can be placed directly in the configuration
+directory, where they will always be executed, or in the profile subdirectories,
+where they will only be executed on changes regarding that specific profile.
+
+Instead (or in addition) to these scripts, you can also place as many executable
+files as you like in subdirectories called `script_name.d` (e.g. `postswitch.d`).
+
+If a script with the same name occurs multiple times, user configuration
+takes precedence over system configuration (as specified by the
+[XDG spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html))
+and profile configuration over general configuration.
+
+As a concrete example, suppose you have the files
+
+- `/etc/xdg/autorandr/postswitch`
+- `~/.config/autorandr/postswitch`
+- `~/.config/autorandr/postswitch.d/notify-herbstluftwm`
+- `~/.config/autorandr/docked/postswitch`
+
+and switch from `mobile` to `docked`. Then
+`~/.config/autorandr/docked/postswitch` is executed, since the profile specific
+configuration takes precedence, and
+`~/.config/autorandr/postswitch.d/notify-herbstluftwm` is executed, since
+it has a unique name.