Browse Source

Modified to follow consistency.

As requested, plugin and inline were reverted to their original spelling.
pull/233/head
rcaballeromx 9 years ago
parent
commit
48b3e1f2e3
  1. 24
      docs/development.md

24
docs/development.md

@ -7,28 +7,28 @@ Before continuing, make sure you've read:
3. [Architecture description](architecture.md) 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)? - 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. - If no - you can morph tokens within core chains.
- Remember that token morphing in core chains is always more simple than writing - 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 or inline rules, if you don't copy existing ones. However,
block and in-line rules are usually faster. block and inline rules are usually faster.
- Sometimes, it's enough to only modify the renderer, 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.
- Plug-ins should not require the `markdown-it` package as dependency in `package.json`. - 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, 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 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), or [rules](https://github.com/markdown-it/markdown-it/tree/master/lib),
doing something similar. It can be more simple to modify existing code, doing something similar. It can be more simple to modify existing code,
instead of writing all from scratch. instead of writing all from scratch.
3. If you did all steps above, but still has questions - ask in 3. If you did all steps above, but still has questions - ask in
[tracker](https://github.com/markdown-it/markdown-it/issues). But, please: [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. "how to learn programming" are not accepted.
- Don't ask us to break [CommonMark](http://commonmark.org/) specification. - Don't ask us to break [CommonMark](http://commonmark.org/) specification.
Such things should be discussed first on [CommonMark forum](http://talk.commonmark.org/). 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: 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. - 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. __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 If you are absolutely sure that something important is missing there - create a
ticket and we will consider adding it as a new charcode. 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? #### Why do you reject some useful things?
We do a markdown parser. It should keep the "markdown spirit". Other things should 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. 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 Of course, if you find the architecture of this parser interesting for another type

Loading…
Cancel
Save