Browse Source

apidocs: updates + added Ruler docs

pull/24/head
Vitaly Puzrin 10 years ago
parent
commit
193e94cb61
  1. 2
      .ndocrc
  2. 8
      README.md
  3. 13
      lib/index.js
  4. 180
      lib/ruler.js
  5. 11
      lib/rules_core/replacements.js
  6. 53
      support/api_header.md

2
.ndocrc

@ -2,7 +2,7 @@
# Common nodeca config # Common nodeca config
################################################################################ ################################################################################
--index "./README.md" --index "./support/api_header.md"
--package "./package.json" --package "./package.json"
--gh-ribbon "{package.homepage}" --gh-ribbon "{package.homepage}"
--output "apidoc" --output "apidoc"

8
README.md

@ -50,23 +50,23 @@ bower install markdown-it --save
// node.js, "classic" way: // node.js, "classic" way:
var MarkdownIt = require('markdown-it'), var MarkdownIt = require('markdown-it'),
md = new MarkdownIt(); md = new MarkdownIt();
console.log(md.render('# markdown-it rulezz!')); var result = md.render('# markdown-it rulezz!');
// node.js, the same, but with sugar: // node.js, the same, but with sugar:
var md = require('markdown-it')(); 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 // browser without AMD, added to "window" on script load
// Note, there are no dash. // Note, there are no dash.
var md = window.markdownit(); var md = window.markdownit();
console.log(md.render('# markdown-it rulezz!')); var result = md.render('# markdown-it rulezz!');
``` ```
Single line rendering, without paragraph wrap: Single line rendering, without paragraph wrap:
```js ```js
var md = require('markdown-it')(); var md = require('markdown-it')();
console.log(md.renderInline('__markdown-it__ rulezz!')); var result = md.renderInline('__markdown-it__ rulezz!');
``` ```
### Configuring ### Configuring

13
lib/index.js

@ -42,23 +42,23 @@ function StateCore(self, src, env) {
* // node.js, "classic" way: * // node.js, "classic" way:
* var MarkdownIt = require('markdown-it'), * var MarkdownIt = require('markdown-it'),
* md = new MarkdownIt(); * md = new MarkdownIt();
* console.log(md.render('# markdown-it rulezz!')); * var result = md.render('# markdown-it rulezz!');
* *
* // node.js, the same, but with sugar: * // node.js, the same, but with sugar:
* var md = require('markdown-it')(); * 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 * // browser without AMD, added to "window" on script load
* // Note, there are no dash. * // Note, there are no dash.
* var md = window.markdownit(); * var md = window.markdownit();
* console.log(md.render('# markdown-it rulezz!')); * var result = md.render('# markdown-it rulezz!');
* ``` * ```
* *
* Single line rendering, without paragraph wrap: * Single line rendering, without paragraph wrap:
* *
* ```javascript * ```javascript
* var md = require('markdown-it')(); * 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. * - __langPrefix__ - `language-`. CSS language class prefix for fenced blocks.
* Can be useful for external highlighters. * Can be useful for external highlighters.
* - __linkify__ - `false`. Set `true` to autoconvert URL-like text to links. * - __linkify__ - `false`. Set `true` to autoconvert URL-like text to links.
* - __typographer__ - `false`. Set `true` to enable some language-neutral * - __typographer__ - `false`. Set `true` to enable [some language-neutral
* replacement + quotes beautification (smartquotes). * 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 * - __quotes__ - `“”‘’`, string. Double + single quotes replacement pairs, when
* typographer enabled and smartquotes on. Set doubles to '«»' for Russian, * typographer enabled and smartquotes on. Set doubles to '«»' for Russian,
* '„“' for German. * '„“' for German.

180
lib/ruler.js

@ -6,9 +6,28 @@
// //
'use strict'; '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() { function Ruler() {
// List of added rules. Each element is: // List of added rules. Each element is:
// //
@ -77,12 +96,31 @@ Ruler.prototype.__compile__ = function () {
}; };
//////////////////////////////////////////////////////////////////////////////// /**
// Public methods * Ruler.at(name, fn [, options])
* - name (String): rule name to replace.
* - fn (Function): new rule function.
// Replace 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) { Ruler.prototype.at = function (name, fn, options) {
var index = this.__find__(name); var index = this.__find__(name);
var opt = options || {}; 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) { Ruler.prototype.before = function (beforeName, ruleName, fn, options) {
var index = this.__find__(beforeName); var index = this.__find__(beforeName);
var opt = options || {}; 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) { Ruler.prototype.after = function (afterName, ruleName, fn, options) {
var index = this.__find__(afterName); var index = this.__find__(afterName);
var opt = options || {}; var opt = options || {};
@ -132,8 +214,29 @@ Ruler.prototype.after = function (afterName, ruleName, fn, options) {
this.__cache__ = null; 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) { Ruler.prototype.push = function (ruleName, fn, options) {
var opt = 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) { Ruler.prototype.enable = function (list, ignoreInvalid) {
if (!Array.isArray(list)) { list = [ list ]; } 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) { Ruler.prototype.enableOnly = function (list, ignoreInvalid) {
if (!Array.isArray(list)) { list = [ list ]; } 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) { Ruler.prototype.disable = function (list, ignoreInvalid) {
if (!Array.isArray(list)) { if (!Array.isArray(list)) {
list = [ 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) { Ruler.prototype.getRules = function (chainName) {
if (this.__cache__ === null) { if (this.__cache__ === null) {
this.__compile__(); this.__compile__();

11
lib/rules_core/replacements.js

@ -1,5 +1,16 @@
// Simple typographyc replacements // Simple typographyc replacements
// //
// '' → ‘’
// "" → “”. Set '«»' for Russian, '„“' for German, empty to disable
// (c) (C) → ©
// (tm) (TM) → ™
// (r) (R) → ®
// +- → ±
// (p) (P) -> §
// ... → … (also ?.... → ?.., !.... → !..)
// ???????? → ???, !!!!! → !!!, `,,` → `,`
// -- → –, --- → —
//
'use strict'; 'use strict';
// TODO: // TODO:

53
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.
Loading…
Cancel
Save