From ea7cc764f3c1841f167e054fcc5f1a726eac8bb2 Mon Sep 17 00:00:00 2001
From: Chris Caron <lead2gold@gmail.com>
Date: Fri, 4 Sep 2020 10:30:19 -0400
Subject: [PATCH] Updated config_yaml (markdown)

---
 config_yaml.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

diff --git a/config_yaml.md b/config_yaml.md
index d037cb5..0182ef1 100644
--- a/config_yaml.md
+++ b/config_yaml.md
@@ -79,7 +79,7 @@ asset:
 # urls below.
 tag: admin, devops
 
-# Define your URLs (Mandatory!)
+# Define your URLs
 urls:
   # One-liner (no colon at the end); just the url as you'd expect it:
   - json://localhost
@@ -112,6 +112,54 @@ urls:
        tag: chris, customer
 ```
 
+## Expanding Configuration Sources
+The YAML based configuration also supports the keyword `include` which allows you to pull more configuration down from other locations. For example:
+```yaml
+# Perhaps this is your default configuration that is always read
+# stored in ~/.config/apprise.yml (or ~/.apprise.yml)
+include:
+  # The following could import all of the configuration located on your
+  # Apprise API:
+  - http://localhost:8080/get/apprise
+```
+
+From there you can easily use the CLI tool from the command line while managing your configuration remotely:
+```bash
+# automatically reads our above configuration
+# Which further imports our additional configuration entries:
+apprise -vv -t "my title" -b "my message body"
+```
+
+You can freely mix/match include statements and Apprise URLs as well, for example:
+```yaml
+# Our config file located in ~/.config/apprise.yml (or ~/.apprise.yml)
+
+# Our imports
+include:
+  # web based include (use https:// too if you like)
+  - http://localhost:8080/get/apprise
+  # A relative config file import (relative to 'this' configuration file)
+  - more_configuration.cfg
+  # Absolute path inclusion works well too:
+  - /etc/apprise/cfg
+
+# you can still include your other URLs here too if you want:
+# Define your URLs
+urls:
+  - json://localhost
+
+  # It's recommended you tag everything and then just
+  # use the --tag (or -g) switch to access the entries. This
+  # is especially important if you're going to start storing your
+  # configuration elsewhere too!
+  - slack://tokenA/tokenB/TokenC:
+    - tag: devops
+```
+
+All loaded configuration files can also contain the `include` keyword as well.  But by default they `include` recursion only happens at 1 level.  If you want to allow more files to be included, you need to specify `--recursion-depth` (`-R`) and set it to the number of recursive levels you will allow the include to occur for.  By default this is set to 1 with the `apprise` tool.
+
+**Note:** For security reasons, an `http://` configuration source can NOT `include` a `file://` source.
+
 ## Web Hosted YAML Configuration
 Apprise can retrieve configuration files from over a network as well using the HTTP protocol.
 For HTTP requests, the **Content-Type** HTTP Header (_which defines Mime Type_) is very important. Apprise will parse remote network hosted configuration files as YAML so long as you're using one of the following **Content-Type** entries: