diff --git a/README.md b/README.md
index 027e556718..74e3d50918 100644
--- a/README.md
+++ b/README.md
@@ -1903,14 +1903,20 @@ for details.
     @echo '{{ style("error") }}OH NO{{ NORMAL }}'
   ```
 
-##### XDG Directories<sup>1.23.0</sup>
+##### User Directories<sup>1.23.0</sup>
 
 These functions return paths to user-specific directories for things like
-configuration, data, caches, executables, and the user's home directory. These
-functions follow the
-[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),
-and are implemented with the
-[`dirs`](https://docs.rs/dirs/latest/dirs/index.html) crate.
+configuration, data, caches, executables, and the user's home directory.
+
+On Unix, these functions follow the
+[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
+
+On MacOS and Windows, these functions return the system-specified user-specific
+directories. For example, `cache_directory()` returns `~/Library/Caches` on
+MacOS and `{FOLDERID_LocalAppData}` on Windows.
+
+See the [`dirs`](https://docs.rs/dirs/latest/dirs/index.html) crate for more
+details.
 
 - `cache_directory()` - The user-specific cache directory.
 - `config_directory()` - The user-specific configuration directory.
@@ -1920,6 +1926,10 @@ and are implemented with the
 - `executable_directory()` - The user-specific executable directory.
 - `home_directory()` - The user's home directory.
 
+If you would like to use XDG base directories on all platforms you can use the
+`env(…)` function with the appropriate environment variable, e.g.,
+`env('XDG_CACHE_HOME')`.
+
 ### Constants
 
 A number of constants are predefined: