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
Split 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
(*) 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
// commonmark mode
@ -89,7 +90,7 @@ var md = require('markdown-it')('commonmark');
var md = require('markdown-it')();
// enable everything
var md = require('markdown-it')('full', {
var md = require('markdown-it')({
html: true,
linkify: true,
typographer: true
@ -123,7 +124,7 @@ var md = require('markdown-it')({
```js
var md = require('markdown-it')()
.use(plugin1)
.use(plugin2, opts)
.use(plugin2, opts, ...)
.use(plugin3);
```
@ -156,7 +157,7 @@ var md = require('markdown-it')({
## 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
[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
Enabled by default:
Embedded (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:
- [Strikethrough](https://help.github.com/articles/github-flavored-markdown/#strikethrough) (GFM)
- [\<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)
Via plugins::
__*__ 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.
- [subscript](https://github.com/markdown-it/markdown-it-sub)
- [superscript](https://github.com/markdown-it/markdown-it-sup)
- [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
By default all rules are enebled, but can be restricted by options. On plugin
load all it's rules are enabled automatically.
```js
// Activate/deactivate rules
// Activate/deactivate rules, with curring
var md = require('markdown-it')()
.enable([ 'ins', 'mark' ])
.disable([ 'table' ]);
.disable([ 'link', 'image' ])
.enable([ 'link' ])
.enable('image');
// Enable everything
md = require('markdown-it')('full', {
@ -198,22 +199,6 @@ md = require('markdown-it')('full', {
linkify: 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.rule1
... (none yet, you can patch input string here)
... (normalize)
block
block.rule1
@ -16,15 +16,15 @@ core
block.ruleX
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.ruleX
core.ruleYY
... (typographer, linkifier)
... (abbreviation, footnote, typographer, linkifier)
```
@ -48,7 +48,7 @@ Difference is simple:
- Tokens are sequence (Array).
- 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, ...).
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).
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
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
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
@ -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).
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:
```js
function (tokens, idx, options, env, self) {
function (tokens, idx, options, env, renderer) {
//...
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)
or [rules](https://github.com/markdown-it/markdown-it/tree/master/lib),
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
[tracker](https://github.com/markdown-it/markdown-it/issues). But, please:
- 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:
- 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.
@ -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?
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
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
be kept separate (in plugins, for example). We have no clear criteria, sorry.

Write Preview
Loading…
Cancel
Save