diff --git a/plugins.md b/plugins.md
new file mode 100644
index 0000000..91e0716
--- /dev/null
+++ b/plugins.md
@@ -0,0 +1,49 @@
+## pandora_client plugins
+
+you can overwrite some elements of pandora_client with custom code. this can be done on a per config basis.
+By default plugins are loaded from ~/.ox/client.d/, you can set "plugin.d" in your config file to load them from another location.
+In that folder you can create multiple .py files, they will be loaded in alphabetical order.
+You can define the following functions in your plugin: parse_path, example_path, ignore_file
+
+Example
+
+    import re
+    
+    def parse_path(client, path):
+        '''
+            parse metadata from file and parsed information,
+            this can include any itemKey defined in your config.jsonc,
+            return None if file can not be parsed,
+            required keys to return are for a path are: title, extension, type
+        '''
+        parts = path.split('/')
+        if len(parts) != 3:
+           return None
+        return {
+            'date': parts[0],
+            'title': parts[1],
+            'extension': parts[-1].split('.')[-1].lower(),
+            'type': parts[-1].split('.')[-1].lower() in ('avi', 'mov', 'webm') and 'video' or None
+        }
+    
+    def example_path(client):
+        '''
+           return a string with a path show as an example for the supported folder structre
+        '''
+        return "2013-03-01/Title/Title.avi"
+    
+    def ignore_file(client, path):
+        '''
+            return True if file should not even be considered.
+            i.e. to filter out .DS_Store, empty files
+        '''
+        filename = os.path.basename(path)
+        if filename.startswith('._') \
+            or filename in ('.DS_Store', ) \
+            or filename.endswith('~') \
+            or not os.path.exists(path) \
+            or os.stat(path).st_size == 0:
+            return True
+        return False
+    
+    
\ No newline at end of file