Public-Mirrors
/
markdown-it
mirror of https://github.com/markdown-it/markdown-it.git
1
0
Fork 0
Code Issues Releases Activity
Browse Source

docs update

pull/25/head
Vitaly Puzrin 10 years ago
parent
9783b530db
commit
c1f3b318de
3 changed files with 37 additions and 51 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 59
      README.md
  2. 19
      docs/architecture.md
  3. 10
      docs/development.md

59
README.md
View File

@ -79,7 +79,8 @@ var result = md.renderInline('__markdown-it__ rulezz!');
### Init with presets and options ### Init with presets and options
(*) preset define combination of active rules and options. Can be (*) preset define combination of active rules and options. Can be
`"full"`|`"commonmark"`|`"zero"` or `"default"` if skipped. `"commonmark"`, `"zero"` or `"default"` (if skipped). See
[API docs](https://markdown-it.github.io/markdown-it/#MarkdownIt.new) for more details.
```js ```js
// commonmark mode // commonmark mode
@ -89,7 +90,7 @@ var md = require('markdown-it')('commonmark');
var md = require('markdown-it')(); var md = require('markdown-it')();
// enable everything // enable everything
var md = require('markdown-it')('full', { var md = require('markdown-it')({
html: true, html: true,
linkify: true, linkify: true,
typographer: true typographer: true
@ -123,7 +124,7 @@ var md = require('markdown-it')({
```js ```js
var md = require('markdown-it')() var md = require('markdown-it')()
.use(plugin1) .use(plugin1)
.use(plugin2, opts) .use(plugin2, opts, ...)
.use(plugin3); .use(plugin3);
``` ```
@ -156,7 +157,7 @@ var md = require('markdown-it')({
## API ## API
[API documentation](https://markdown-it.github.io/markdown-it/) __[API documentation](https://markdown-it.github.io/markdown-it/)__
If you are going to write plugins - take a look at If you are going to write plugins - take a look at
[Development info](https://github.com/markdown-it/markdown-it/tree/master/docs). [Development info](https://github.com/markdown-it/markdown-it/tree/master/docs).
@ -164,33 +165,33 @@ If you are going to write plugins - take a look at
## Syntax extensions ## Syntax extensions
Enabled by default: Embedded (enabled by default):
- [Tables](https://help.github.com/articles/github-flavored-markdown/#tables) (GFM) - [Tables](https://help.github.com/articles/github-flavored-markdown/#tables) (GFM)
- [\<del>](https://help.github.com/articles/github-flavored-markdown/#strikethrough) - [Strikethrough](https://help.github.com/articles/github-flavored-markdown/#strikethrough) (GFM)
(GFM strikethrough) - `~~deleted text~~`
Disabled by default:
- [\<sup>](http://johnmacfarlane.net/pandoc/README.html#superscripts-and-subscripts) - `19^th^` Via plugins::
- [\<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 - [subscript](https://github.com/markdown-it/markdown-it-sub)
[Critic Markup](http://criticmarkup.com/), but you will still be able to use - [superscript](https://github.com/markdown-it/markdown-it-sup)
old-style rules via external plugins if you prefer. - [footnote](https://github.com/markdown-it/markdown-it-footnote)
- [definition list](https://github.com/markdown-it/markdown-it-deflist)
- [abbreviation](https://github.com/markdown-it/markdown-it-abbr)
- [insert](https://github.com/markdown-it/markdown-it-ins)
- [mark](https://github.com/markdown-it/markdown-it-mark)
### Manage rules ### Manage rules
By default all rules are enebled, but can be restricted by options. On plugin
load all it's rules are enabled automatically.
```js ```js
// Activate/deactivate rules // Activate/deactivate rules, with curring
var md = require('markdown-it')() var md = require('markdown-it')()
.enable([ 'ins', 'mark' ]) .disable([ 'link', 'image' ])
.disable([ 'table' ]); .enable([ 'link' ])
.enable('image');
// Enable everything // Enable everything
md = require('markdown-it')('full', { md = require('markdown-it')('full', {
@ -198,22 +199,6 @@ md = require('markdown-it')('full', {
linkify: true, linkify: true,
typographer: true, typographer: true,
}); });
// Manually enable rules, disabled by default:
var md = require('markdown-it')()
.enable([
/* core */
'abbr',
/* block */
'footnote',
'deflist',
/* inline */
'footnote_inline',
'ins',
'mark',
'sub',
'sup'
]);
``` ```

19
docs/architecture.md
View File

@ -8,7 +8,7 @@ Input data is piped via nestesd chains of rules. There are 3 nested chains -
``` ```
core core
core.rule1 core.rule1
... (none yet, you can patch input string here) ... (normalize)
block block
block.rule1 block.rule1
@ -16,15 +16,15 @@ core
block.ruleX block.ruleX
core.ruleXX core.ruleXX
... (references, abbreviations, footnotes) ... (nothing yet)
inline (applyed to each block token with "inline type") inline (applyed to each block token with "inline" type)
inline.rule1 inline.rule1
... ...
inline.ruleX inline.ruleX
core.ruleYY core.ruleYY
... (typographer, linkifier) ... (abbreviation, footnote, typographer, linkifier)
``` ```
@ -48,7 +48,7 @@ Difference is simple:
- Tokens are sequence (Array). - Tokens are sequence (Array).
- Opening and closing tags are separate tokens. - Opening and closing tags are separate tokens.
- There are special token object, "inline containers", having nested token - There are special token objects, "inline containers", having nested token
sequences with inline markup (bold, italic, text, ...). sequences with inline markup (bold, italic, text, ...).
Each token has common fields: Each token has common fields:
@ -90,7 +90,8 @@ registered in one of chain with unique name.
Rules are managed by names via [Ruler](https://markdown-it.github.io/markdown-it/#Ruler) instances and `enable` / `disable` methods in [MarkdownIt](https://markdown-it.github.io/markdown-it/#MarkdownIt). Rules are managed by names via [Ruler](https://markdown-it.github.io/markdown-it/#Ruler) instances and `enable` / `disable` methods in [MarkdownIt](https://markdown-it.github.io/markdown-it/#MarkdownIt).
You can note, that some rules have "validation mode" - in this mode rule does not You can note, that some rules have "validation mode" - in this mode rule does not
modify token stream, and only search end of token. It's one of important design principle - token stream is "write only" on block & inline parse stages. modify token stream, and only look ahead for the end of token. It's one of
important design principle - token stream is "write only" on block & inline parse stages.
Parser is designed to keep rules independent. You can safely disable any, or Parser is designed to keep rules independent. You can safely disable any, or
add new one. There are no universal recipes how to create new rules - design of add new one. There are no universal recipes how to create new rules - design of
@ -99,7 +100,7 @@ can investigate existing rules & plugins to see possible approaches.
Also, in complex cases you can try to ask for help in tracker. Condition is very Also, in complex cases you can try to ask for help in tracker. Condition is very
simple - it should be clear from your ticket, that you studied docs, sources, simple - it should be clear from your ticket, that you studied docs, sources,
and tryed to do something yourself. We never reject with help to real developpers. and tried to do something yourself. We never reject with help to real developpers.
## Renderer ## Renderer
@ -107,11 +108,11 @@ and tryed to do something yourself. We never reject with help to real developper
After token stream is generated, it's passed to [renderer](https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js). After token stream is generated, it's passed to [renderer](https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js).
It just plays all tokens, passing each to rule with the same name as token type. It just plays all tokens, passing each to rule with the same name as token type.
Randerer rules are located in `md.renderer.rules[name]` and are simple functions Renderer rules are located in `md.renderer.rules[name]` and are simple functions
with the same signature: with the same signature:
```js ```js
function (tokens, idx, options, env, self) { function (tokens, idx, options, env, renderer) {
//... //...
return htmlResult; return htmlResult;
} }

10
docs/development.md
View File

@ -22,7 +22,7 @@ Prior to continue, make sure you've readed:
[plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin) [plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
or [rules](https://github.com/markdown-it/markdown-it/tree/master/lib), or [rules](https://github.com/markdown-it/markdown-it/tree/master/lib),
doing something similar. It can me more simple to modify existing code, doing something similar. It can me more simple to modify existing code,
instead of writing from scratch. instead of writing all from scratch.
3. If you did all steps above, but still has questions - ask in 3. If you did all steps above, but still has questions - ask in
[tracker](https://github.com/markdown-it/markdown-it/issues). But, please: [tracker](https://github.com/markdown-it/markdown-it/issues). But, please:
- Be specific. Generic questions like "how to do plugins" and - Be specific. Generic questions like "how to do plugins" and
@ -35,7 +35,7 @@ Prior to continue, make sure you've readed:
To simplify search: To simplify search:
- add to `package.json` keyswords `markdown-it` and `markdown-it-plugin` for plugins - add to `package.json` keyswords `markdown-it` and `markdown-it-plugin` for plugins.
- add keyword `markdown-it` for any other related packages. - add keyword `markdown-it` for any other related packages.
@ -69,13 +69,13 @@ __Note.__ Don't try to replace text with html markup! That's not secure.
#### Why my inline rule is not executed? #### Why my inline rule is not executed?
Inline parser skips porsion of texts for the best speed. It stops only on [small set of chars](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_inline/text.js), which can be tokens. We did not made this list extendable, also for performance reasons. Inline parser skips peases of texts for the best speed. It stops only on [small set of chars](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_inline/text.js), which can be tokens. We did not made this list extendable, also for performance reasons.
If you are absolutely sure, that something important is missed there - create a If you are absolutely sure, that something important is missed there - create a
ticket and we will add new charcodes. ticket and we will consider adding new charcodes.
#### Why do you reject to accept some useful things? #### Why do you reject some useful things?
We do markdown parser. It should keep "markdown spirit". Other things should We do markdown parser. It should keep "markdown spirit". Other things should
be kept separate (in plugins, for example). We have no clear criteria, sorry. be kept separate (in plugins, for example). We have no clear criteria, sorry.

Write Preview
Loading…
Cancel
Save