Browse Source

Docs clarification

pull/24/head
Vitaly Puzrin 10 years ago
parent
commit
b170cd1e52
  1. 11
      README.md
  2. 38
      docs/architecture.md
  3. 24
      docs/development.md

11
README.md

@ -40,8 +40,12 @@ bower install markdown-it --save
## Usage examples ## Usage examples
See __[API documentation](https://markdown-it.github.io/markdown-it/)__ for more See also:
info and examples.
- __[API documentation](https://markdown-it.github.io/markdown-it/)__ - for more
info and examples.
- [Development info](https://github.com/markdown-it/markdown-it/tree/master/docs) -
for plugins writers.
### Simple ### Simple
@ -152,6 +156,9 @@ var md = require('markdown-it')({
[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).
## Syntax extensions ## Syntax extensions

38
docs/architecture.md

@ -2,8 +2,8 @@
## Data flow ## Data flow
Parse process is unified as much as possible. Input data is piped via nestesd Input data is piped via nestesd chains of rules. There are 3 nested chains -
chains of rules. There are 3 "main" chains (core / block / inline): `core`, `block` & `inline`:
``` ```
core core
@ -44,42 +44,44 @@ data and protect code from clutter.
## Token stream ## Token stream
Instead of traditional AST we use more low-level data representation - tokens. Instead of traditional AST we use more low-level data representation - tokens.
Difference is very simple. 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 object, "inline containers", having nested token
sequences with inline markup (bold, italic, text) sequences with inline markup (bold, italic, text, ...).
Each token has 2 mandatory fields: Each token has common fields:
- __type__ - token name. - __type__ - token name.
- __level__ - nesting level, useful to seek matched pair. - __level__ - nesting level, useful to seek closeing pair.
- __lines__ - [begin, end], for block tokens only. Range of input lines, - __lines__ - [begin, end], for block tokens only. Range of input lines,
compiled to this token compiled to this token.
Inline container (`type === "inline"`) has additional properties: Inline container (`type === "inline"`) has additional properties:
- __content__ - raw text, unparsed inline content. - __content__ - raw text, unparsed inline content.
- __children__ - token stream for parsed content. - __children__ - token stream for parsed content.
See [renderer source](https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js)
for available tokens and those properties. Currently there are no special
requirements on tokens naming and additional fields.
In total, token stream is: In total, token stream is:
- Array of paired or single "block" tokens, on top level: - On the top level - array of paired or single "block" tokens:
- open/close for headers, lists, blockquotes paragraphs - open/close for headers, lists, blockquotes, paragraphs, ...
- codes, fenced blocks, horisontal rules, html blocks, inlines containers - codes, fenced blocks, horisontal rules, html blocks, inlines containers
- Inline containers have "substream" Array with inline tags: - Each inline containers have `.children` property with token stream for inline content:
- open/close for strong, em, link, code, ... - open/close for strong, em, link, code, ...
- text, line breaks - text, line breaks
Why not AST? Because it's not needed for our tasks. We follow KISS principle. Why not AST? Because it's not needed for our tasks. We follow KISS principle.
If you whish - you can call parser withour renderer and convert token stream If you whish - you can call parser without renderer and convert token stream
to AST. to AST.
Where to search more details about tokens:
- [Renderer source](https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js)
- [Live demo](https://markdown-it.github.io/) - type your text ant click `debug` tab.
## Parse process ## Parse process
This was mentioned in [Data flow](#data-flow), but let's repeat sequence again: This was mentioned in [Data flow](#data-flow), but let's repeat sequence again:

24
docs/development.md

@ -9,14 +9,15 @@ Prior to continue, make sure you've readed:
## General considerations for plugins. ## General considerations for plugins.
1. Try to understand, where your plugin rule sould be located 1. Try to understand, where your plugin rule sould be located.
- Will it conflict with existing markup (by priority)? - Will it conflict with existing markup (by priority)?
- If yes - you need to write inline or block rule. - If yes - you need to write inline or block rule.
- If no - you can morth tokens in core chain. - If no - you can morth tokens in core chain.
- Remember, that tokens morphing in core is always more simple than writing - Remember, that tokens morphing in core is always more simple than writing
block / inline rules. However, block / inline rules are usually faster block / inline rules (if you don't copy existing one). However,
block & inline rules are usually faster.
- Sometime it's enougth to modify renderer only (for example, to add - Sometime it's enougth to modify renderer only (for example, to add
header IDs or target=_blank for the links) header IDs or `target="_blank"` for the links).
2. Search existing [plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin) 2. Search existing [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,
@ -39,6 +40,7 @@ To simplify search:
## FAQ ## FAQ
#### I need async rule, how to do it? #### I need async rule, how to do it?
Sorry. You can't do it directly. All complex parsers are sync by nature. But you Sorry. You can't do it directly. All complex parsers are sync by nature. But you
@ -47,4 +49,18 @@ can use workarounds:
1. On parse phase, replace content by random number and store it in `env`. 1. On parse phase, replace content by random number and store it in `env`.
2. Do async processing over collected data. 2. Do async processing over collected data.
3. Render content and replace those random numbers with text 3. Render content and replace those random numbers with text
(or replace first, then render) (or replace first, then render).
Or you can render html, then parse is to DOM (or
[cheerio](https://github.com/cheeriojs/cheerio) AST) and apply transformations
in more convenient way.
#### How to replace part of text token with link?
Righ sequence is to split text to several tokens and add link tokens between.
Result will be: `text` + `link_open` + `text` + `link_close` + `text`.
See implementations of [linkify](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/linkify.js) & [emoji](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/replace.js) - those do similar things.
__Note.__ Don't try to replace text with html markup! That's not secure.

Loading…
Cancel
Save