apidocs: updates + added Ruler docs

.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"

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

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.

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__();

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:

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 `<strong>` with `<b>` in rendered result:
+
+```javascript
+var md = require('markdown-it')();
+
+md.renderer.rules.strong_open  = function () { return '<b>'; };
+md.renderer.rules.strong_close = function () { return '</b>'; };
+
+var result = md.renderInline(...);
+```
+
+See classes doc for all available features and more examples.