Added API documentation, tweaks to markdown-include

Author: Sethen Maleno

README.md

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

docs/_README.md

@@ -0,0 +1,22 @@
+## API !heading
+
+When using as a module, markdown-include offers an API for you to work with markdown files as detailed below:
+
+---
+
+#include "docs/api/build_link.md"
+#include "docs/api/build_link_string.md"
+#include "docs/api/compile_files.md"
+#include "docs/api/compile_heading_tags.md"
+#include "docs/api/find_heading_tags.md"
+#include "docs/api/find_include_tags.md"
+#include "docs/api/parse_heading_tag.md"
+#include "docs/api/parse_include_tag.md"
+#include "docs/api/process_file.md"
+#include "docs/api/process_include_tags.md"
+#include "docs/api/replace_include_tags.md"
+#include "docs/api/replace_with.md"
+#include "docs/api/resolve_custom_tags.md"
+#include "docs/api/strip_tag.md"
+#include "docs/api/strip_tags_in_file.md"
+#include "docs/api/write_file.md"

docs/api.md

@@ -0,0 +1,25 @@
+### `buildLink` !heading
+
+#### Description
+
+A method for making markdown style anchor tags.
+
+#### Signature
+
+`buildLink(title: String, anchor: String) => String`
+
+#### Parameters
+
+| Parameter(s)    | Type     | Description                          |
+|:---------------:|:--------:|:------------------------------------:|
+| `title`         | `String` | Title of markdown style link.        |
+| `anchor`        | `String` | Markdown style anchor for linking.   |
+
+#### Example
+
+```javascript
+var markdownInclude = require('markdown-include');
+markdownInclude.buildLink("My Link String", "#my-link-string"); // [My Link String](#my-link-string)
+```
+
+---

docs/api/_README.md

@@ -0,0 +1,24 @@
+### `buildLinkString` !heading
+
+#### Description
+
+A method for taking strings and building friendly markdown links.  This is mostly used internally for building the table of contents.
+
+#### Signature
+
+`buildLinkString(str: String) => String`
+
+#### Parameters
+
+| Parameter(s)    | Type     | Description                                                            |
+|:---------------:|:--------:|:----------------------------------------------------------------------:|
+| `str`           | `String` | File path of where everything should be compiled, like `README.md`.    |
+
+#### Example
+
+```javascript
+var markdownInclude = require('markdown-include');
+markdownInclude.buildLinkString("My Link String"); // my-link-string
+```
+
+---

docs/api/build_link.md

@@ -0,0 +1,26 @@
+### `compileFiles` !heading
+
+#### Description
+
+This is probably the most important method in markdown-include.  It takes a path to your markdown.json file, reads your options and returns a promise.  When the promise is resolved it returns the data to you.  This is exactly the same as running markdown-include in the command line as it runs through the whole lifecycle.
+
+#### Signature
+
+`compileFiles(path: String) => Object<Promise>` 
+
+#### Parameters
+
+| Parameter(s)   | Type     | Description                                              |
+|:--------------:|:--------:|:--------------------------------------------------------:|
+| `path`         | `String` | Compiles files when given the path to `markdown.json`    |
+
+#### Example
+
+```javascript
+var markdownInclude = require('markdown-include');
+markdownInclude.compileFiles("path/to/markdown.json").then(function (data) {
+	// do something with compiled files
+});
+```
+
+---

docs/api/build_link_string.md

@@ -0,0 +1,24 @@
+### `compileHeadingTags` !heading
+
+#### Description
+
+A method for compiling heading tags (`!heading`) in a given file.
+
+#### Signature
+
+`compileHeadingTags(file: String)`
+
+#### Parameters
+
+| Parameter(s)    | Type     | Description                          |
+|:---------------:|:--------:|:------------------------------------:|
+| `file`          | `String` | File with `!heading` tags            |
+
+#### Example
+
+```javascript
+var markdownInclude = require('markdown-include');
+markdownInclude.compileHeadingTags("my_file.md");
+```
+
+---

docs/api/compile_files.md

@@ -0,0 +1,24 @@
+### `findHeadingTags` !heading
+
+#### Description
+
+A method for finding heading tags (`!heading`) in a string.
+
+#### Signature
+
+`findHeadingTags(data: String) => Array<String>`
+
+#### Parameters
+
+| Parameter(s)    | Type     | Description                          |
+|:---------------:|:--------:|:------------------------------------:|
+| `data`          | `String` | Data with `!heading` tags            |
+
+#### Example
+
+```javascript
+var markdownInclude = require('markdown-include');
+markdownInclude.findHeadingTags("### A Heading !heading"); // [ "### A Heading !heading" ]
+```
+
+---

docs/api/compile_heading_tags.md

@@ -0,0 +1,24 @@
+### `findIncludeTags` !heading
+
+#### Description
+
+A method for finding include tags (`#include "my-include.md"`) in a string.
+
+#### Signature
+
+`findIncludeTags(data: String) => Array<String>`
+
+#### Parameters
+
+| Parameter(s)    | Type     | Description                                  |
+|:---------------:|:--------:|:--------------------------------------------:|
+| `data`          | `String` | Data with `#include "my-include.md"` tags    |
+
+#### Example
+
+```javascript
+var markdownInclude = require('markdown-include');
+markdownInclude.findIncludeTags('#include "my-include.md"'); // [ '#include "my-include.md"' ]
+```
+
+---