Browse Source

Fixed grammar and spelling errors.

Fixed grammar and spelling while keeping the consistent use of 'plugin' and 'inline'.
pull/234/head
rcaballeromx 9 years ago
parent
commit
2412895f3a
  1. 51
      docs/development.md

51
docs/development.md

@ -1,6 +1,6 @@
# Development recommendations # Development recommendations
Prior to continue, make sure you've read: Before continuing, make sure you've read:
1. [README](https://github.com/markdown-it/markdown-it#markdown-it) 1. [README](https://github.com/markdown-it/markdown-it#markdown-it)
2. [API documentation](https://markdown-it.github.io/markdown-it/) 2. [API documentation](https://markdown-it.github.io/markdown-it/)
@ -9,17 +9,17 @@ Prior to continue, make sure you've read:
## General considerations for plugins. ## General considerations for plugins.
1. Try to understand where your plugin rule sould be located. 1. Try to find the right place for your plugin rule:
- Will it conflict with existing markup (by priority)? - Will it conflict with existing markup (by priority)?
- If yes - you need to write an inline or block rule. - If yes - you need to write an inline or block rule.
- If no - you can morph tokens in core chain. - If no - you can morph tokens within core chains.
- Remember that token morphing in core is always more simple than writing - Remember that token morphing in core chains is always more simple than writing
block / inline rules (if you don't copy existing ones). However, block or inline rules, if you don't copy existing ones. However,
block & inline rules are usually faster. block and inline rules are usually faster.
- Sometime it's enougth to modify renderer only (for example, to add - Sometimes, it's enough to only modify the renderer, for example, to add
header IDs or `target="_blank"` for the links). header IDs or `target="_blank"` for the links.
- Plugins should not require `markdown-it` package as dependency in `package.json`. - Plugins should not require the `markdown-it` package as dependency in `package.json`.
If you need access to internals, those are available via parser instance, If you need access to internals, those are available via a parser instance,
passed on plugin load. See properties of main class and nested objects. passed on plugin load. See properties of main class and nested objects.
2. Search existing 2. Search existing
[plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin) [plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
@ -52,37 +52,36 @@ 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 it to DOM (or Alternatively, you can render HTML, then parse it to DOM, or
[cheerio](https://github.com/cheeriojs/cheerio) AST) and apply transformations [cheerio](https://github.com/cheeriojs/cheerio) AST, and apply transformations
in more convenient way. in a more convenient way.
#### How to replace part of text token with link? #### How to replace part of text token with link?
Righ sequence is to split text to several tokens and add link tokens between. The right sequence is to split text to several tokens and add link tokens in between.
Result will be: `text` + `link_open` + `text` + `link_close` + `text`. The 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 text token splits. See implementations of [linkify](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/linkify.js) and [emoji](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/replace.js) - those do text token splits.
__Note.__ Don't try to replace text with html markup! That's not secure. __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?
The inline parser skips pieces of texts for the best speed. It stops only on [a 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. The inline parser skips pieces of texts to optimize speed. It stops only on [a 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 extensible for performance reasons too.
If you are absolutely sure that something important is missing there - create a If you are absolutely sure that something important is missing there - create a
ticket and we will consider adding new charcodes. ticket and we will consider adding it as a new charcode.
#### Why do you reject some useful things? #### Why do you reject some useful things?
We do a markdown parser. It should keep "markdown spirit". Other things should We do a markdown parser. It should keep the "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.
Probably, you will find [CommonMark forum](http://talk.commonmark.org/) useful to read to understand us better. Probably, you will find [CommonMark forum](http://talk.commonmark.org/) a useful read to understand us better.
Of cause, if you find architecture of this parser interesting for another type Of course, if you find the architecture of this parser interesting for another type
of markup - you are welcome to reuse it in another project. of markup, you are welcome to reuse it in another project.

Loading…
Cancel
Save