diff --git a/README.md b/README.md index c018ca0..4a745f9 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ * [`stripTag`](#striptag) * [`stripTagsInFile`](#striptagsinfile) * [`writeFile`](#writefile) -* [How To Make Custom Tags](#how-to-make-custom-tags) +* [How To Make Plugins](#how-to-make-plugins) * [Tutorial](#tutorial) * [How It Works](#how-it-works) @@ -76,6 +76,8 @@ For each heading that you would like to be included in a table of contents just markdown-include is available on npm for easy installation: +fuck! + ``` npm install markdown-include ``` @@ -541,15 +543,15 @@ markdownInclude.writeFile('contents').then(function (data) { ``` --- -# How To Make Custom Tags +# How To Make Plugins -Custom tags are now supported as of 0.4.0 of markdown-include. Adding custom tags to your documentation is quite easy to do. +Plugins are now supported as of 0.4.0 of markdown-include. Adding plugins to markdown-include to facilitate the transformation of custom tags is quite trivial. -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. +Plugins are best 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. +Let's pretend we want to add a custom tag called `!myTag` that follows the pattern of `#phrase !myTag`. All we need to do is register the plugin with markdown-include First, require markdown-include: @@ -557,29 +559,32 @@ First, require markdown-include: 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: +Second, register your plugin with with your desired pattern to match and desired replacement. You can replace your tag with another string to do your desired work: ```javascript var markdownInclude = require('markdown-include'); -markdownInclude.customTags.push({ +markdownInclude.registerPlugin({ pattern: /^#.+ !myTag/gm, - replacement: 'myString!' + replace: '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: +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 (you must return a value to replace with): ```javascript var markdownInclude = require('markdown-include'); -markdownInclude.customTags.push({ +markdownInclude.registerPlugin({ pattern: /^#.+ !myTag/gm, - replacement: function (tag) { + replace: function (tag) { // do something with tag... + return 'myString!' } }); ``` -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. +`pattern` is the regular expression that should be looked for. `replace` is your desired replacement for the tag once it's found. + +This gives you free range to do whatever you want with the tag you want to replace. 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: @@ -589,6 +594,14 @@ markdownInclude.compileFiles('../path/to/markdown.json').then(function () { }); ``` +You can also use another form of registering a plugins if it fits your coding style better: + +``` +markdownInclude.registerPlugin(/^#.+ !myTag/gm, function (tag) { + return 'my replacement!'; +}); +``` + # How It Works diff --git a/bin/cli.js b/bin/cli.js index 0e4f560..7cc64e9 100755 --- a/bin/cli.js +++ b/bin/cli.js @@ -6,6 +6,10 @@ var markdownJson = process.argv[2]; var markdownInclude = require('../markdown-include'); +markdownInclude.registerPlugin(/^#.+ !myTag/gm, function () { + return 'fuck!'; +}); + markdownInclude.compileFiles(markdownJson).then(function () { console.info(markdownInclude.options.build + ' have been built successfully'); }); \ No newline at end of file diff --git a/docs/_README.md b/docs/_README.md index 67dd70d..3dc3650 100644 --- a/docs/_README.md +++ b/docs/_README.md @@ -4,5 +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_to_make_plugins.md" #include "docs/how_it_works.md" \ No newline at end of file diff --git a/docs/how_to_install.md b/docs/how_to_install.md index 6ae9816..7e5f7c6 100644 --- a/docs/how_to_install.md +++ b/docs/how_to_install.md @@ -2,6 +2,8 @@ markdown-include is available on npm for easy installation: +#something !myTag + ``` npm install markdown-include ``` diff --git a/docs/how_to_make_custom_tags.md b/docs/how_to_make_custom_tags.md deleted file mode 100644 index 86a8a19..0000000 --- a/docs/how_to_make_custom_tags.md +++ /dev/null @@ -1,48 +0,0 @@ -# How To Make Custom Tags !heading - -Custom tags are now supported as of 0.4.0 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 -}); -``` - diff --git a/docs/how_to_make_plugins.md b/docs/how_to_make_plugins.md new file mode 100644 index 0000000..c69ae0b --- /dev/null +++ b/docs/how_to_make_plugins.md @@ -0,0 +1,59 @@ +# How To Make Plugins !heading + +Plugins are now supported as of 0.4.0 of markdown-include. Adding plugins to markdown-include to facilitate the transformation of custom tags is quite trivial. + +Plugins are best 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`. All we need to do is register the plugin with markdown-include + +First, require markdown-include: + +```javascript +var markdownInclude = require('markdown-include'); +``` + +Second, register your plugin with with your desired pattern to match and desired replacement. You can replace your tag with another string to do your desired work: + +```javascript +var markdownInclude = require('markdown-include'); +markdownInclude.registerPlugin({ + pattern: /^#.+ !myTag/gm, + replace: 'myString!' +}); +``` + +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 (you must return a value to replace with): + +```javascript +var markdownInclude = require('markdown-include'); +markdownInclude.registerPlugin({ + pattern: /^#.+ !myTag/gm, + replace: function (tag) { + // do something with tag... + return 'myString!' + } +}); +``` + +`pattern` is the regular expression that should be looked for. `replace` is your desired replacement for the tag once it's found. + +This gives you free range to do whatever you want with the tag you want to replace. 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 +}); +``` + +You can also use another form of registering a plugins if it fits your coding style better: + +``` +markdownInclude.registerPlugin(/^#.+ !myTag/gm, function (tag) { + return 'my replacement!'; +}); +``` + diff --git a/markdown-include.js b/markdown-include.js index 315efb9..88e302f 100644 --- a/markdown-include.js +++ b/markdown-include.js @@ -305,6 +305,18 @@ exports.processIncludeTags = function (file, currentFile, tags) { return collection; }; +exports.registerPlugin = function () { + if (arguments[0].pattern && arguments[0].replace) { + this.customTags.push(arguments[0]); + } + else { + this.customTags.push({ + pattern: arguments[0], + replace: arguments[1] + }); + } +}; + /** * Replaces include tags with actual content from files * @param {String} file File content diff --git a/package.json b/package.json index 84d075c..1eae0ea 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "markdown-include", - "version": "0.4.1", + "version": "0.4.2", "description": "Include markdown files into other markdown files with C style syntax.", "main": "markdown-include.js", "repository": {