diff --git a/docs/development.md b/docs/development.md index 7eec754..7391ff2 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,6 +1,6 @@ # 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) 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. -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)? - If yes - you need to write an inline or block rule. - - If no - you can morph tokens in core chain. - - Remember that token morphing in core is always more simple than writing - block / inline rules (if you don't copy existing ones). However, - block & inline rules are usually faster. - - Sometime it's enougth to modify renderer only (for example, to add - header IDs or `target="_blank"` for the links). - - Plugins should not require `markdown-it` package as dependency in `package.json`. - If you need access to internals, those are available via parser instance, + - If no - you can morph tokens within core chains. + - Remember that token morphing in core chains is always more simple than writing + block or inline rules, if you don't copy existing ones. However, + block and inline rules are usually faster. + - Sometimes, it's enough to only modify the renderer, for example, to add + header IDs or `target="_blank"` for the links. + - Plugins should not require the `markdown-it` package as dependency in `package.json`. + 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. 2. Search existing [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`. 2. Do async processing over collected data. -3. Render content and replace those random numbers with text - (or replace first, then render). +3. Render content and replace those random numbers with text; or replace first, then render. -Or you can render html, then parse it to DOM (or -[cheerio](https://github.com/cheeriojs/cheerio) AST) and apply transformations -in more convenient way. +Alternatively, you can render HTML, then parse it to DOM, or +[cheerio](https://github.com/cheeriojs/cheerio) AST, and apply transformations +in a 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`. +The right sequence is to split text to several tokens and add link tokens in between. +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? -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 -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? -We do a markdown parser. It should keep "markdown spirit". Other things should -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. +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. +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 markup - you are welcome to reuse it in another project. +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.