markdown-it
Advanced tools
Comparing version 2.1.2 to 2.1.3
@@ -1,4 +0,12 @@ | ||
2.1.1 / 2014-12-23 | ||
2.1.3 / 2014-12-24 | ||
------------------ | ||
- Added curring to `set`/`configure`/`enable`/`disable` methods. | ||
- Demo rework - now can include plugins. | ||
- Docs update. | ||
2.1.2 / 2014-12-23 | ||
------------------ | ||
- Exposed helpers into parser instances (for plugins). | ||
@@ -5,0 +13,0 @@ - Removed utils from global export - been in instances seems enougth. |
@@ -71,2 +71,3 @@ // Main perser class | ||
assign(this.options, options); | ||
return this; | ||
}; | ||
@@ -91,2 +92,3 @@ | ||
} | ||
return this; | ||
}; | ||
@@ -101,2 +103,3 @@ | ||
}, this); | ||
return this; | ||
}; | ||
@@ -111,2 +114,3 @@ | ||
}, this); | ||
return this; | ||
}; | ||
@@ -113,0 +117,0 @@ |
{ | ||
"name": "markdown-it", | ||
"version": "2.1.2", | ||
"version": "2.1.3", | ||
"description": "Markdown-it - modern pluggable markdown parser.", | ||
@@ -9,3 +9,4 @@ "keywords": [ | ||
"commonmark", | ||
"markdown-it" | ||
"markdown-it", | ||
"markdown-it-plugin" | ||
], | ||
@@ -12,0 +13,0 @@ "homepage": "https://github.com/markdown-it/markdown-it", |
269
README.md
@@ -11,9 +11,24 @@ # markdown-it | ||
- Supports the [CommonMark](http://commonmark.org/) spec + | ||
[syntax extensions](#syntax-extensions) + sugar (URL autolinking, typographer). | ||
- Supports the CommonMark spec + syntax extensions + sugar (URL autolinking, typographer). | ||
- Configurable syntax! You can add new rules and even replace existing ones. | ||
- [High speed](#benchmark)! | ||
- Community written __[plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin)__ and [utilities](https://www.npmjs.org/browse/keyword/markdown-it) on npm. | ||
- High speed! | ||
- Community written __[plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin)__ and [other packages](https://www.npmjs.org/browse/keyword/markdown-it) on npm. | ||
__Table of content__ | ||
- [Install](#install) | ||
- [Usage](#usage) | ||
- [Configuring](#configuring) | ||
- [constructor(preset, options)](#constructorpreset-options) | ||
- [.set({ keys: values })](#set-keys-values-) | ||
- [.use(plugin, options)](#useplugin-options) | ||
- [Syntax highlighting](#syntax-highlighting) | ||
- [Typographer](#typographer) | ||
- [Syntax extensions](#syntax-extensions) | ||
- [Manage rules](#manage-rules) | ||
- [Benchmark](#benchmark) | ||
- [Authors](#authors) | ||
- [References / Thanks](#references--thanks) | ||
- [License](#license) | ||
## Install | ||
@@ -36,3 +51,3 @@ | ||
```js | ||
// node.js, standard way: | ||
// node.js, "classic" way: | ||
var MarkdownIt = require('markdown-it'), | ||
@@ -53,22 +68,49 @@ md = new MarkdownIt(); | ||
### Options | ||
### Configuring | ||
By default markdown-it is configured to be similar to GFM, but with HTML disabled. | ||
This is easy to change if you prefer to use different settings. | ||
By default `markdown-it` is configured to be similar to GFM, but with HTML disabled. | ||
This is easy to change if you prefer different settings. | ||
There are two ways to define options. | ||
Usually, you will define everything via constructor. | ||
#### constructor(preset, options) | ||
- __preset__ (String): "full"|"commonmark"|Optional. | ||
__preset__ (String) - `"full"`|`"commonmark"`, optional. | ||
Define options in the constructor: | ||
`markdown-it` offers some presets as a convenience to quickly enable/disable | ||
active syntax rules and options for common use cases. | ||
- ["commonmark"](https://github.com/markdown-it/markdown-it/blob/master/lib/presets/commonmark.js) - enable strict [CommonMark](http://commonmark.org/) mode. | ||
- ["full"](https://github.com/markdown-it/markdown-it/blob/master/lib/presets/full.js) - | ||
all rules enabled, but still without html, typographer & autolinker. | ||
- [default](https://github.com/markdown-it/markdown-it/blob/master/lib/presets/default.js) - | ||
when no preset name given. | ||
```js | ||
// commonmark mode | ||
var md = require('markdown-it')('commonmark'); | ||
// default mode | ||
var md = require('markdown-it')(); | ||
// enable everything | ||
var md = require('markdown-it')('full', { | ||
html: true, | ||
linkify: true, | ||
typographer: true | ||
}); | ||
``` | ||
__options__ | ||
```js | ||
// Actual default values | ||
var md = require('markdown-it')({ | ||
html: false, // Enable HTML tags in source | ||
xhtmlOut: false, // Use '/' to close single tags (<br />) | ||
xhtmlOut: false, // Use '/' to close single tags (<br />). | ||
// This is only for full CommonMark compatibility. | ||
breaks: false, // Convert '\n' in paragraphs into <br> | ||
langPrefix: 'language-', // CSS language prefix for fenced blocks | ||
langPrefix: 'language-', // CSS language prefix for fenced blocks. Can be | ||
// useful for external highlighters. | ||
linkify: false, // Autoconvert URL-like text to links | ||
@@ -84,21 +126,17 @@ | ||
// Highlighter function. Should return escaped HTML, | ||
// or '' if the source string is not changed | ||
// or '' if the source string is not changed and should be escaped externaly. | ||
highlight: function (/*str, lang*/) { return ''; } | ||
}); | ||
console.log(md.render('# markdown-it rulezz!')); | ||
// => <h1>markdown-it rulezz!</h1> | ||
``` | ||
#### .set | ||
Or define options via the `.set()` method: | ||
#### .set({ keys: values }) | ||
Probably, you will never need it. But you can change options after | ||
constructor call. | ||
```js | ||
var md = require('markdown-it')(); | ||
md.set({ | ||
html: true, | ||
breaks: true | ||
}); | ||
var md = require('markdown-it')() | ||
.set({ html: true, breaks: true }) | ||
.set({ typographer, true }); | ||
``` | ||
@@ -108,35 +146,17 @@ | ||
instance on the fly. If you need multiple configurations it's best to create | ||
multiple instances and initialize each with a configuration that is ideal for | ||
that instance. | ||
multiple instances and initialize each with separate config. | ||
### Presets | ||
#### .use(plugin, options) | ||
`markdown-it` offers some "presets" as a convenience to quickly enable/disable | ||
active syntax rules and options for common use cases. | ||
Sugar to activate plugins. | ||
#### commonmark | ||
Enable strict [CommonMark](http://commonmark.org/) mode with the `commonmark` preset: | ||
```js | ||
var md = require('markdown-it')('commonmark'); | ||
var md = require('markdown-it')() | ||
.use(plugin1) | ||
.use(plugin2, opts) | ||
.use(plugin3); | ||
``` | ||
#### full | ||
Enable all available rules (but still with default options, if not set): | ||
```js | ||
var md = require('markdown-it')('full'); | ||
// Or with options: | ||
var md = require('markdown-it')('full', { | ||
html: true, | ||
linkify: true, | ||
typographer: true | ||
}); | ||
``` | ||
### Syntax highlighting | ||
@@ -147,3 +167,3 @@ | ||
```js | ||
var hljs = require('highlight.js') // https://highlightjs.org/ | ||
var hljs = require('highlight.js') // https://highlightjs.org/ | ||
@@ -169,59 +189,2 @@ // Actual default values | ||
### Syntax extensions | ||
Enabled by default: | ||
- [Tables](https://help.github.com/articles/github-flavored-markdown/#tables) (GFM) | ||
- [\<del>](https://help.github.com/articles/github-flavored-markdown/#strikethrough) | ||
(GFM strikethrough) - `~~deleted text~~` | ||
Disabled by default: | ||
- [\<sup>](http://johnmacfarlane.net/pandoc/README.html#superscripts-and-subscripts) - `19^th^` | ||
- [\<sub>](http://johnmacfarlane.net/pandoc/README.html#superscripts-and-subscripts) - `H~2~0` | ||
- [abbreviations](https://michelf.ca/projects/php-markdown/extra/#abbr) | ||
- [footnotes](http://johnmacfarlane.net/pandoc/README.html#footnotes) | ||
- __\<ins>__ - `++inserted text++` (experimental) | ||
- __\<mark>__ - `==marked text==` (experimental) | ||
__*__ Experimental extensions can be changed later for something like | ||
[Critic Markup](http://criticmarkup.com/), but you will still be able to use | ||
old-style rules via external plugins if you prefer. | ||
### Manage rules | ||
```js | ||
var md = require('markdown-it')(); | ||
md.inline.ruler.enable([ 'ins', 'mark' ]); | ||
md.block.ruler.disable([ 'table' ]); | ||
// Enable everything | ||
md = require('markdown-it')('full', { | ||
html: true, | ||
linkify: true, | ||
typographer: true, | ||
}); | ||
// | ||
// Manually enable rules, disabled by default: | ||
// | ||
var md = require('markdown-it')(); | ||
md.block.ruler.core([ | ||
'abbr' | ||
]); | ||
md.block.ruler.enable([ | ||
'footnote', | ||
'deflist' | ||
]); | ||
md.block.ruler.enable([ | ||
'footnote_inline', | ||
'ins', | ||
'mark', | ||
'sub', | ||
'sup' | ||
]); | ||
``` | ||
### Typographer | ||
@@ -239,3 +202,3 @@ | ||
// Disable rules at all: | ||
md.core.ruler.disable([ 'replacements', 'smartquotes' ]); | ||
md.disable([ 'replacements', 'smartquotes' ]); | ||
@@ -261,46 +224,57 @@ // Actual default replacements: | ||
### Plugins | ||
### Syntax extensions | ||
Easily load plugins with the `.use()` method: | ||
Enabled by default: | ||
```js | ||
var md = require('markdown-it')(); | ||
- [Tables](https://help.github.com/articles/github-flavored-markdown/#tables) (GFM) | ||
- [\<del>](https://help.github.com/articles/github-flavored-markdown/#strikethrough) | ||
(GFM strikethrough) - `~~deleted text~~` | ||
md.use(plugin1) | ||
.use(plugin2, opts) | ||
.use(plugin3); | ||
``` | ||
Disabled by default: | ||
- [\<sup>](http://johnmacfarlane.net/pandoc/README.html#superscripts-and-subscripts) - `19^th^` | ||
- [\<sub>](http://johnmacfarlane.net/pandoc/README.html#superscripts-and-subscripts) - `H~2~0` | ||
- [abbreviations](https://michelf.ca/projects/php-markdown/extra/#abbr) | ||
- [footnotes](http://johnmacfarlane.net/pandoc/README.html#footnotes) | ||
- __\<ins>__ - `++inserted text++` (experimental) | ||
- __\<mark>__ - `==marked text==` (experimental) | ||
## References / Thanks | ||
__*__ Experimental extensions can be changed later for something like | ||
[Critic Markup](http://criticmarkup.com/), but you will still be able to use | ||
old-style rules via external plugins if you prefer. | ||
Big thanks to [John MacFarlane](https://github.com/jgm) for his work on the | ||
CommonMark spec and reference implementations. His work saved us a lot of time | ||
during this project's development. | ||
**Related Links:** | ||
### Manage rules | ||
1. https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS, | ||
also contains latest spec & online demo. | ||
2. http://talk.commonmark.org - CommonMark forum, good place to collaborate | ||
developers' efforts. | ||
```js | ||
// Activate/deactivate rules | ||
var md = require('markdown-it')() | ||
.enable([ 'ins', 'mark' ]) | ||
.disable([ 'table' ]); | ||
// Enable everything | ||
md = require('markdown-it')('full', { | ||
html: true, | ||
linkify: true, | ||
typographer: true, | ||
}); | ||
## Development / Modification | ||
// Manually enable rules, disabled by default: | ||
var md = require('markdown-it')() | ||
.enable([ | ||
/* core */ | ||
'abbr', | ||
/* block */ | ||
'footnote', | ||
'deflist', | ||
/* inline */ | ||
'footnote_inline', | ||
'ins', | ||
'mark', | ||
'sub', | ||
'sup' | ||
]); | ||
``` | ||
Parser consists of several responsibilities chains, filled with rules. You can | ||
reconfigure anyone as you wish. Render also can be modified and extended. See | ||
source code to understand details. Pay attention to these properties: | ||
```js | ||
MarkdownIt.core | ||
MarkdownIt.core.ruler | ||
MarkdownIt.block | ||
MarkdownIt.block.ruler | ||
MarkdownIt.inline | ||
MarkdownIt.inline.ruler | ||
MarkdownIt.renderer | ||
MarkdownIt.renderer.rules | ||
``` | ||
## Benchmark | ||
@@ -332,4 +306,17 @@ | ||
## References / Thanks | ||
Big thanks to [John MacFarlane](https://github.com/jgm) for his work on the | ||
CommonMark spec and reference implementations. His work saved us a lot of time | ||
during this project's development. | ||
**Related Links:** | ||
- https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS, | ||
also contains latest spec & online demo. | ||
- http://talk.commonmark.org - CommonMark forum, good place to collaborate | ||
developers' efforts. | ||
## License | ||
[MIT](https://github.com/markdown-it/markdown-it/blob/master/LICENSE) |
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is too big to display
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
557822
14909
313