diff --git a/.ndocrc b/.ndocrc index 047f632..d3383e9 100644 --- a/.ndocrc +++ b/.ndocrc @@ -2,7 +2,7 @@ # Common nodeca config ################################################################################ ---index "./README.md" +--index "./support/api_header.md" --package "./package.json" --gh-ribbon "{package.homepage}" --output "apidoc" diff --git a/README.md b/README.md index 2025c9b..41bf0e8 100644 --- a/README.md +++ b/README.md @@ -50,23 +50,23 @@ bower install markdown-it --save // node.js, "classic" way: var MarkdownIt = require('markdown-it'), md = new MarkdownIt(); -console.log(md.render('# markdown-it rulezz!')); +var result = md.render('# markdown-it rulezz!'); // node.js, the same, but with sugar: var md = require('markdown-it')(); -console.log(md.render('# markdown-it rulezz!')); +var result = md.render('# markdown-it rulezz!'); // browser without AMD, added to "window" on script load // Note, there are no dash. var md = window.markdownit(); -console.log(md.render('# markdown-it rulezz!')); +var result = md.render('# markdown-it rulezz!'); ``` Single line rendering, without paragraph wrap: ```js var md = require('markdown-it')(); -console.log(md.renderInline('__markdown-it__ rulezz!')); +var result = md.renderInline('__markdown-it__ rulezz!'); ``` ### Configuring diff --git a/lib/index.js b/lib/index.js index 640db2e..07d285d 100644 --- a/lib/index.js +++ b/lib/index.js @@ -42,23 +42,23 @@ function StateCore(self, src, env) { * // node.js, "classic" way: * var MarkdownIt = require('markdown-it'), * md = new MarkdownIt(); - * console.log(md.render('# markdown-it rulezz!')); + * var result = md.render('# markdown-it rulezz!'); * * // node.js, the same, but with sugar: * var md = require('markdown-it')(); - * console.log(md.render('# markdown-it rulezz!')); + * var result = md.render('# markdown-it rulezz!'); * * // browser without AMD, added to "window" on script load * // Note, there are no dash. * var md = window.markdownit(); - * console.log(md.render('# markdown-it rulezz!')); + * var result = md.render('# markdown-it rulezz!'); * ``` * * Single line rendering, without paragraph wrap: * * ```javascript * var md = require('markdown-it')(); - * console.log(md.renderInline('__markdown-it__ rulezz!')); + * var result = md.renderInline('__markdown-it__ rulezz!'); * ``` **/ @@ -96,8 +96,9 @@ function StateCore(self, src, env) { * - __langPrefix__ - `language-`. CSS language class prefix for fenced blocks. * Can be useful for external highlighters. * - __linkify__ - `false`. Set `true` to autoconvert URL-like text to links. - * - __typographer__ - `false`. Set `true` to enable some language-neutral - * replacement + quotes beautification (smartquotes). + * - __typographer__ - `false`. Set `true` to enable [some language-neutral + * replacement](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.js) + + * quotes beautification (smartquotes). * - __quotes__ - `“”‘’`, string. Double + single quotes replacement pairs, when * typographer enabled and smartquotes on. Set doubles to '«»' for Russian, * '„“' for German. diff --git a/lib/ruler.js b/lib/ruler.js index c9b7d06..0be79ef 100644 --- a/lib/ruler.js +++ b/lib/ruler.js @@ -6,9 +6,28 @@ // 'use strict'; - -//////////////////////////////////////////////////////////////////////////////// - +/** + * class Ruler + * + * Helper class, used by [[MarkdownIt#core]], [[MarkdownIt#block]] and + * [[MarkdownIt#inline]] to manage sequences of functions (rules): + * + * - keep rules in defined order + * - assign the name to each rule + * - enable/disable rules + * - add/replace rules + * - allow assign rules to additional named chains (in the same) + * - cacheing lists of active rules + * + * You will not need use this class directly until write plugins. For simple + * rules control use [[MarkdownIt.disable]], [[MarkdownIt.enable]] and + * [[MarkdownIt.use]]. + **/ + + +/** + * new Ruler() + **/ function Ruler() { // List of added rules. Each element is: // @@ -77,12 +96,31 @@ Ruler.prototype.__compile__ = function () { }; -//////////////////////////////////////////////////////////////////////////////// -// Public methods - - -// Replace rule function -// +/** + * Ruler.at(name, fn [, options]) + * - name (String): rule name to replace. + * - fn (Function): new rule function. + * - options (Object): new rule options (not mandatory). + * + * Replace rule by name with new function & options. Throws error if name not + * found. + * + * ##### Options: + * + * - __alt__ - array with names of "alternate" chains. + * + * ##### Example + * + * Replace existing typorgapher replacement rule with new one: + * + * ```javascript + * var md = require('markdown-it')(); + * + * md.core.ruler.at('replacements', function replace(state) { + * //... + * }); + * ``` + **/ Ruler.prototype.at = function (name, fn, options) { var index = this.__find__(name); var opt = options || {}; @@ -95,8 +133,30 @@ Ruler.prototype.at = function (name, fn, options) { }; -// Add rule to chain before one with given name. -// +/** + * Ruler.before(beforeName, ruleName, fn [, options]) + * - beforeName (String): new rule will be added before this one. + * - ruleName (String): name of added rule. + * - fn (Function): rule function. + * - options (Object): rule options (not mandatory). + * + * Add new rule to chain before one with given name. See also + * [[Ruler.after]], [[Ruler.push]]. + * + * ##### Options: + * + * - __alt__ - array with names of "alternate" chains. + * + * ##### Example + * + * ```javascript + * var md = require('markdown-it')(); + * + * md.block.ruler.before('paragraph', 'my_rule', function replace(state) { + * //... + * }); + * ``` + **/ Ruler.prototype.before = function (beforeName, ruleName, fn, options) { var index = this.__find__(beforeName); var opt = options || {}; @@ -114,8 +174,30 @@ Ruler.prototype.before = function (beforeName, ruleName, fn, options) { }; -// Add rule to chain after one with given name. -// +/** + * Ruler.after(afterName, ruleName, fn [, options]) + * - afterName (String): new rule will be added after this one. + * - ruleName (String): name of added rule. + * - fn (Function): rule function. + * - options (Object): rule options (not mandatory). + * + * Add new rule to chain after one with given name. See also + * [[Ruler.before]], [[Ruler.push]]. + * + * ##### Options: + * + * - __alt__ - array with names of "alternate" chains. + * + * ##### Example + * + * ```javascript + * var md = require('markdown-it')(); + * + * md.inline.ruler.after('text', 'my_rule', function replace(state) { + * //... + * }); + * ``` + **/ Ruler.prototype.after = function (afterName, ruleName, fn, options) { var index = this.__find__(afterName); var opt = options || {}; @@ -132,8 +214,29 @@ Ruler.prototype.after = function (afterName, ruleName, fn, options) { this.__cache__ = null; }; -// Add rule to the end of chain. -// +/** + * Ruler.push(ruleName, fn [, options]) + * - ruleName (String): name of added rule. + * - fn (Function): rule function. + * - options (Object): rule options (not mandatory). + * + * Push new rule to the end of chain. See also + * [[Ruler.before]], [[Ruler.after]]. + * + * ##### Options: + * + * - __alt__ - array with names of "alternate" chains. + * + * ##### Example + * + * ```javascript + * var md = require('markdown-it')(); + * + * md.core.ruler.push('emphasis', 'my_rule', function replace(state) { + * //... + * }); + * ``` + **/ Ruler.prototype.push = function (ruleName, fn, options) { var opt = options || {}; @@ -148,8 +251,16 @@ Ruler.prototype.push = function (ruleName, fn, options) { }; -// Enable rules by names. -// +/** + * Ruler.enable(list [, ignoreInvalid]) + * - list (String|Array): list of rule names to enable. + * - ignoreInvalid (Boolean): set `true` to ignore errors when rule not found. + * + * Enable rules with given names. If any rule name not found - throw Error. + * Errors can be disabled by second param. + * + * See also [[Ruler.disable]], [[Ruler.enableOnly]]. + **/ Ruler.prototype.enable = function (list, ignoreInvalid) { if (!Array.isArray(list)) { list = [ list ]; } @@ -168,8 +279,16 @@ Ruler.prototype.enable = function (list, ignoreInvalid) { }; -// Enable rules by whitelisted names (others will be disables). -// +/** + * Ruler.enableOnly(list [, ignoreInvalid]) + * - list (String|Array): list of rule names to enable (whitelist). + * - ignoreInvalid (Boolean): set `true` to ignore errors when rule not found. + * + * Enable rules with given names, and disable everything else. If any rule name + * not found - throw Error. Errors can be disabled by second param. + * + * See also [[Ruler.disable]], [[Ruler.enable]]. + **/ Ruler.prototype.enableOnly = function (list, ignoreInvalid) { if (!Array.isArray(list)) { list = [ list ]; } @@ -179,8 +298,16 @@ Ruler.prototype.enableOnly = function (list, ignoreInvalid) { }; -// Disable rules by names. -// +/** + * Ruler.disable(list [, ignoreInvalid]) + * - list (String|Array): list of rule names to disable. + * - ignoreInvalid (Boolean): set `true` to ignore errors when rule not found. + * + * Disable rules with given names. If any rule name not found - throw Error. + * Errors can be disabled by second param. + * + * See also [[Ruler.enable]], [[Ruler.enableOnly]]. + **/ Ruler.prototype.disable = function (list, ignoreInvalid) { if (!Array.isArray(list)) { list = [ list ]; @@ -201,8 +328,15 @@ Ruler.prototype.disable = function (list, ignoreInvalid) { }; -// Get rules list as array of functions. -// +/** + * Ruler.getRules(chainName) -> Array + * + * Return array of active functions (rules) for given chain name. It analyzes + * rules configuration, compiles caches if not exists and returns result. + * + * Default chain name is `''` (empty string). It can't be skipped. That's + * done intentionally, to keep signature monomorphic for high speed. + **/ Ruler.prototype.getRules = function (chainName) { if (this.__cache__ === null) { this.__compile__(); diff --git a/lib/rules_core/replacements.js b/lib/rules_core/replacements.js index 875e902..1359058 100644 --- a/lib/rules_core/replacements.js +++ b/lib/rules_core/replacements.js @@ -1,5 +1,16 @@ // Simple typographyc replacements // +// '' → ‘’ +// "" → “”. Set '«»' for Russian, '„“' for German, empty to disable +// (c) (C) → © +// (tm) (TM) → ™ +// (r) (R) → ® +// +- → ± +// (p) (P) -> § +// ... → … (also ?.... → ?.., !.... → !..) +// ???????? → ???, !!!!! → !!!, `,,` → `,` +// -- → –, --- → — +// 'use strict'; // TODO: diff --git a/support/api_header.md b/support/api_header.md new file mode 100644 index 0000000..aa7b754 --- /dev/null +++ b/support/api_header.md @@ -0,0 +1,53 @@ +# markdown-it API + +In most cases you will use `markdown-it` in very simple way: + +```javascript +var md = require('markdown-it')(); + +var result = md.render(your_markdown_string); + +// Or for inline (without paragraths & blocks) +var resultInline = md.renderInline(your_markdown_inline_string); +``` + +Advanced usage consist of this steps: + +1. Create instance with desired preset & options. +2. Add plugins. +3. Enable/Disable additional rules. +4. Rewrite renderer functions. +5. Use result to call `.render()` or `.renderInline()` method. + + +Example 1. Minimalistic mode with bold, italic and line breaks: + +```javascript +var md = require('markdown-it')('zero', { breaks: true }) + .enable([ 'newline', 'emphasis' ]); + +var result = md.renderInline(...); +``` + +Example 2. Load plugin and disable tables: + +```javascript +var md = require('markdown-it')() + .use(require('markdown-it-emoji')) + .disable('table'); + +var result = md.render(...); +``` + +Example 3. Replace `` with `` in rendered result: + +```javascript +var md = require('markdown-it')(); + +md.renderer.rules.strong_open = function () { return ''; }; +md.renderer.rules.strong_close = function () { return ''; }; + +var result = md.renderInline(...); +``` + +See classes doc for all available features and more examples.