Added documentation for custom tags, array for custom tags in markdown-include

Author: Sethen Maleno

README.md

@@ -24,6 +24,8 @@
     * [`stripTag`](#striptag)
     * [`stripTagsInFile`](#striptagsinfile)
     * [`writeFile`](#writefile)
+* [How To Make Custom Tags](#how-to-make-custom-tags)
+  * [Tutorial](#tutorial)
 * [How It Works](#how-it-works)
 
 
@@ -537,6 +539,55 @@ markdownInclude.writeFile('contents').then(function (data) {
 ```
 
 ---
+# How To Make Custom Tags
+
+Custom tags are now supported as of 0.3.2 of markdown-include.  Adding custom tags to your documentation is quite easy to do.
+
+Custom tags can only be used when markdown-include is being required as a module.  If you wish to make this available via the command line, you must require markdown-include in a node module and call it from the command line.
+
+## Tutorial
+
+Let's pretend we want to add a custom tag called `!myTag` that follows the pattern of `#phrase !myTag`.  We need to register the custom tag with markdown-include in it's `customTags` array.
+
+First, require markdown-include:
+
+```javascript
+var markdownInclude = require('markdown-include');
+```
+
+Second, register your tag with your desired replacement.  You can replace your tag with either another string or use a function to do your desired work.  This is done with objects added to an array, like so:
+
+```javascript
+var markdownInclude = require('markdown-include');
+markdownInclude.customTags.push({
+	pattern: /^#.+ !myTag/gm,
+	replacement: 'myString!'
+});
+```
+
+`pattern` is the regular expression that should be looked for.  `replacement` is your desired replacement for the tag once it's found.  In the example above, we're just replacing our tag with a string.  If you would rather use a function, you can do this like so:
+
+```javascript
+var markdownInclude = require('markdown-include');
+markdownInclude.customTags.push({
+	pattern: /^#.+ !myTag/gm,
+	replacement: function (tag) {
+		// do something with tag...
+	}
+});
+```
+
+This gives you free range to do whatever you want with the tag in question.  Once the tag is encountered markdown-include will run the function.
+
+After the tag and it's replacement is registed, it's business as usual:
+
+```javascript
+markdownInclude.compileFiles('../path/to/markdown.json').then(function () {
+	// do something after compiling
+});
+```
+
+
 # How It Works
 
 markdown-include works by recursively going through files based on the tags that are found.  For instance, consider the following in a `_README.md` file:

docs/_README.md

@@ -4,4 +4,5 @@
 #include "docs/markdown-json.md"
 #include "docs/how_to_use_module.md"
 #include "docs/api/_README.md"
+#include "docs/how_to_make_custom_tags.md"
 #include "docs/how_it_works.md"

docs/how_to_make_custom_tags.md

@@ -0,0 +1,48 @@
+# How To Make Custom Tags !heading
+
+Custom tags are now supported as of 0.3.2 of markdown-include.  Adding custom tags to your documentation is quite easy to do.
+
+Custom tags can only be used when markdown-include is being required as a module.  If you wish to make this available via the command line, you must require markdown-include in a node module and call it from the command line.
+
+## Tutorial !heading
+
+Let's pretend we want to add a custom tag called `!myTag` that follows the pattern of `#phrase !myTag`.  We need to register the custom tag with markdown-include in it's `customTags` array.
+
+First, require markdown-include:
+
+```javascript
+var markdownInclude = require('markdown-include');
+```
+
+Second, register your tag with your desired replacement.  You can replace your tag with either another string or use a function to do your desired work.  This is done with objects added to an array, like so:
+
+```javascript
+var markdownInclude = require('markdown-include');
+markdownInclude.customTags.push({
+	pattern: /^#.+ !myTag/gm,
+	replacement: 'myString!'
+});
+```
+
+`pattern` is the regular expression that should be looked for.  `replacement` is your desired replacement for the tag once it's found.  In the example above, we're just replacing our tag with a string.  If you would rather use a function, you can do this like so:
+
+```javascript
+var markdownInclude = require('markdown-include');
+markdownInclude.customTags.push({
+	pattern: /^#.+ !myTag/gm,
+	replacement: function (tag) {
+		// do something with tag...
+	}
+});
+```
+
+This gives you free range to do whatever you want with the tag in question.  Once the tag is encountered markdown-include will run the function.
+
+After the tag and it's replacement is registed, it's business as usual:
+
+```javascript
+markdownInclude.compileFiles('../path/to/markdown.json').then(function () {
+	// do something after compiling
+});
+```
+

markdown-include.js

@@ -17,6 +17,7 @@ this.ignorePattern = new RegExp('^#include\\s"(.+\\/|\\/|\\w|-|\\/)+.md"' + this
 this.headingPattern = new RegExp('^#+\\s.+' + this.headingTag, 'gm');
 this.tableOfContents = '';
 this.build = {};
+this.customTags = [];
 
 /**
  * Build content item for navigation