diff --git a/.tmux.conf b/.tmux.conf
index 53f76bb..f3660a0 100644
--- a/.tmux.conf
+++ b/.tmux.conf
@@ -1208,6 +1208,16 @@ run -b '[ -z "#{window_active}" ] && [ -z "#{version}" ] && tmux set display-tim
 #   tmux_conf_theme_clock_colour=${tmux_conf_theme_clock_colour:-#00afff} # light blue
 #   tmux_conf_theme_clock_style=${tmux_conf_theme_clock_style:-24}
 #
+#   # -- custom variables ---------------------------------------------------
+#
+#   if [ -f ~/.tmux.conf.local ] && [ x"$(cut -c3- ~/.tmux.conf.local | sh 2>/dev/null -s printf probe)" = x"probe" ]; then
+#     replacements=$(perl -n -e 'print if s!^#\s+([^()\s]+)\s*\(\)\s*{\s*\n!s%#{\1}%#(cut -c3- ~/.tmux.conf.local | sh -s \1)%g; !p' < ~/.tmux.conf.local)
+#     status_left=$(echo "$status_left" | perl -p -e "$replacements")
+#     status_right=$(echo "$status_right" | perl -p -e "$replacements")
+#   fi
+#
+#   # -----------------------------------------------------------------------
+#
 #   tmux setw -g window-style "$window_style" \; setw -g window-active-style "$window_active_style" \;\
 #        setw -g pane-border-style "fg=$tmux_conf_theme_pane_border_fg,bg=$tmux_conf_theme_pane_border_bg" \; set -g pane-active-border-style "fg=$tmux_conf_theme_pane_active_border_fg,bg=$tmux_conf_theme_pane_active_border_bg" \;\
 #        set -g display-panes-colour "$tmux_conf_theme_pane_indicator" \; set -g display-panes-active-colour "$tmux_conf_theme_pane_active_indicator" \;\
diff --git a/.tmux.conf.local b/.tmux.conf.local
index 069d81b..2de8620 100644
--- a/.tmux.conf.local
+++ b/.tmux.conf.local
@@ -1,3 +1,4 @@
+# : << EOF
 # https://github.com/gpakosz/.tmux
 # (‑●‑●)> dual licensed under the WTFPL v2 license and the MIT license,
 #         without any warranty.
@@ -293,3 +294,28 @@ tmux_conf_copy_to_os_clipboard=false
 
 # move status line to top
 #set -g status-position top
+
+
+# -- custom variables ----------------------------------------------------------
+# to define a custom #{foo} variable, define a POSIX shell function between the
+# '# EOF' and the '# "$@"' lines. Please note that the opening brace { character
+# must be on the same line as the function name otherwise the parse won't detect
+# it.
+#
+# then, use #{foo} in e.g. the 'tmux_conf_theme_status_left' or the
+# 'tmux_conf_theme_status_right' variables.
+
+# # /!\ do not remove the following line
+# EOF
+#
+# weather() {
+#   curl -m 1 wttr.in?format=3 2>/dev/null
+#   sleep 900 # sleep for 15 minutes, throttle network requests whatever the value of status-interval
+# }
+#
+# online() {
+#   ping -t 1 -c 1 1.1.1.1 >/dev/null 2>&1 && printf '✔' || printf '✘'
+# }
+#
+# "$@"
+# # /!\ do not remove the previous line
diff --git a/README.md b/README.md
index d4e2b0e..52978a4 100644
--- a/README.md
+++ b/README.md
@@ -202,10 +202,10 @@ customize it further to your needs. Instead of altering the `~/.tmux.conf` file
 and diverging from upstream, the proper way is to edit the `~/.tmux.conf.local`
 file.
 
-Please refer to the default `~/.tmux.conf.local` file to know more about
-variables you can adjust to alter different behaviors. Pressing `<prefix> e`
-will open `~/.tmux.conf.local` with the editor defined by the `$EDITOR`
-environment variable (defaults to `vim` when empty).
+Please refer to the sample `.tmux.conf.local` file to know more about variables
+you can adjust to alter different behaviors. Pressing `<prefix> e` will open
+`~/.tmux.conf.local` with the editor defined by the `$EDITOR` environment
+variable (defaults to `vim` when empty).
 
 ### Enabling the Powerline look
 
@@ -231,8 +231,8 @@ To make use of these symbols, there are several options:
 
 Please see the [Powerline manual] for further details.
 
-Then edit the `~/.tmux.conf.local` file (`<prefix> e`) and adjust the following
-variables:
+Then edit your `~/.tmux.conf.local` copy (with `<prefix> e`) and adjust the
+following variables:
 
 ```
 tmux_conf_theme_left_separator_main='\uE0B0'
@@ -245,7 +245,7 @@ tmux_conf_theme_right_separator_sub='\uE0B3'
 Contrary to the first iterations of this configuration, by now you have total
 control on the content and order of `status-left` and `status-right`.
 
-Edit the `~/.tmux.conf.local` file (`<prefix> e`) and adjust the
+Edit your `~/.tmux.conf.local` copy (`<prefix> e`) and adjust the
 `tmux_conf_theme_status_left` and `tmux_conf_theme_status_right` variables to
 your own preferences.
 
@@ -287,6 +287,9 @@ minutes whatever the value of `status-interval`.
 
 [wttr.in]: https://github.com/chubin/wttr.in#one-line-output
 
+💡 You can also define your own custom variables. See the sample
+`.tmux.conf.local` file for instructions.
+
 Finally, remember `tmux_conf_theme_status_left` and
 `tmux_conf_theme_status_right` end up being given to tmux as `status-left` and
 `status-right` which means they're passed through `strftime()`. As such, the `%`