diff --git a/docs/open_actions.rst b/docs/open_actions.rst
index f820bfc94..a9b4dd7df 100644
--- a/docs/open_actions.rst
+++ b/docs/open_actions.rst
@@ -100,3 +100,41 @@ lines. The various available criteria are:
 ``file``
     A shell glob pattern that must match the filename, for example:
     ``image-??.png``
+
+
+Scripting the opening of files with kitty on macOS
+-------------------------------------------------------
+
+On macOS you can use :guilabel:`Open With` in Finder or drag and drop files
+onto the kitty dock icon to open them with kitty. The default action
+is to open text files in your editor and images using the icat kitten.
+Shell scripts are run in a shell. You can customize these actions by creating
+a :file:`launch-actions.conf` file in the kitty config directory, just like
+the :file:`open-actions.conf` file above. For example::
+
+.. code:: conf
+
+    # Open script files based on their shebangs
+    protocol file
+    ext sh,command,tool
+    action launch --hold --type=os-window kitty +shebang $FILE_PATH {SHELL}
+
+    # Open shell specific script files
+    protocol file
+    ext fish,bash,zsh
+    action launch --hold --type=os-window kitty +shebang $FILE_PATH __ext__
+
+    # Open directories
+    protocol file
+    mime inode/directory
+    action launch --type=os-window --cwd $FILE_PATH
+
+    # Open text files without fragments in the editor
+    protocol file
+    mime text/*
+    action launch --type=os-window $EDITOR $FILE_PATH
+
+    # Open image files with icat
+    protocol file
+    mime image/*
+    action launch --type=os-window kitty +kitten icat --hold $FILE_PATH