From 315eb0dceaf7fad8d2abec3962b584023e49b13c Mon Sep 17 00:00:00 2001 From: rcaballeromx Date: Mon, 18 Apr 2016 13:09:41 -0500 Subject: [PATCH 1/3] Fixed grammar and spelling errors. While reading the content, I found several spelling and grammar mistakes. I fixed all I could find during a superficial edit. --- docs/development.md | 65 ++++++++++++++++++++++----------------------- 1 file changed, 32 insertions(+), 33 deletions(-) diff --git a/docs/development.md b/docs/development.md index 7eec754..8db5b9d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,34 +1,34 @@ # 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/) 3. [Architecture description](architecture.md) -## General considerations for plugins. +## General considerations for plug-ins. -1. Try to understand where your plugin rule sould be located. +1. Try to find the right place for your plug-in 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, - passed on plugin load. See properties of main class and nested objects. + - If yes - you need to write an in-line or block rule. + - If no - you can morph tokens within core chains. + - Remember that token morphing in core chains is always more simple than writing + block or in-line rules, if you don't copy existing ones. However, + block and in-line 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. + - Plug-ins 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 plug-in load. See properties of main class and nested objects. 2. Search existing - [plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin) + [plug-ins](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 be more simple to modify existing code, 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 + - Be specific. Generic questions like "how to do plug-ins" and "how to learn programming" are not accepted. - Don't ask us to break [CommonMark](http://commonmark.org/) specification. Such things should be discussed first on [CommonMark forum](http://talk.commonmark.org/). @@ -38,7 +38,7 @@ Prior to continue, make sure you've read: 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 plug-ins. - add keyword `markdown-it` for any other related packages. @@ -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? +#### Why my in-line 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 in-line 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 plug-ins, 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. From 48b3e1f2e31f9d6b6c78a9a1374c1542faa416b8 Mon Sep 17 00:00:00 2001 From: rcaballeromx Date: Mon, 18 Apr 2016 13:37:29 -0500 Subject: [PATCH 2/3] Modified to follow consistency. As requested, plugin and inline were reverted to their original spelling. --- docs/development.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/development.md b/docs/development.md index 8db5b9d..3a4aa51 100644 --- a/docs/development.md +++ b/docs/development.md @@ -7,28 +7,28 @@ Before continuing, make sure you've read: 3. [Architecture description](architecture.md) -## General considerations for plug-ins. +## General considerations for plugins. -1. Try to find the right place for your plug-in rule: +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 in-line or block rule. + - If yes - you need to write an inline or block rule. - If no - you can morph tokens within core chains. - Remember that token morphing in core chains is always more simple than writing - block or in-line rules, if you don't copy existing ones. However, - block and in-line rules are usually faster. + 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. - Plug-ins 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 plug-in load. See properties of main class and nested objects. + passed on plugin load. See properties of main class and nested objects. 2. Search existing - [plug-ins](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), doing something similar. It can be more simple to modify existing code, 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 plug-ins" and + - Be specific. Generic questions like "how to do plugins" and "how to learn programming" are not accepted. - Don't ask us to break [CommonMark](http://commonmark.org/) specification. Such things should be discussed first on [CommonMark forum](http://talk.commonmark.org/). @@ -38,7 +38,7 @@ Before continuing, make sure you've read: To simplify search: -- add to `package.json` keyswords `markdown-it` and `markdown-it-plugin` for plug-ins. +- add to `package.json` keyswords `markdown-it` and `markdown-it-plugin` for plugins. - add keyword `markdown-it` for any other related packages. @@ -69,9 +69,9 @@ See implementations of [linkify](https://github.com/markdown-it/markdown-it/blob __Note.__ Don't try to replace text with HTML markup! That's not secure. -#### Why my in-line rule is not executed? +#### Why my inline rule is not executed? -The in-line 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. +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 it as a new charcode. @@ -80,7 +80,7 @@ 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 the "markdown spirit". Other things should -be kept separate, in plug-ins, 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/) a useful read to understand us better. Of course, if you find the architecture of this parser interesting for another type From e9a5d2dd62eb86df434f07dd65b6bce095cc9571 Mon Sep 17 00:00:00 2001 From: rcaballeromx Date: Mon, 18 Apr 2016 13:39:11 -0500 Subject: [PATCH 3/3] Fixed one remaining instance. One instance of plugin was missed because of capitalization. --- docs/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development.md b/docs/development.md index 3a4aa51..7391ff2 100644 --- a/docs/development.md +++ b/docs/development.md @@ -18,7 +18,7 @@ Before continuing, make sure you've read: 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. - - Plug-ins should not require the `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 a parser instance, passed on plugin load. See properties of main class and nested objects. 2. Search existing