Added security info

README.md

@@ -12,6 +12,7 @@ __[Live demo](https://markdown-it.github.io)__
 - Follows the __[CommonMark spec](http://spec.commonmark.org/)__ + adds syntax extensions & sugar (URL autolinking, typographer).
 - Configurable syntax! You can add new rules and even replace existing ones.
 - High speed.
+- [Safe](https://github.com/markdown-it/markdown-it/tree/master/docs/security.md) by default.
 - Community-written __[plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin)__ and [other packages](https://www.npmjs.org/browse/keyword/markdown-it) on npm.
 
 __Table of content__

docs/security.md

@@ -0,0 +1,35 @@
+# Security
+
+Many people don't understand, that markdown format does not care much about
+security. In many cases you have to pass output to sanitizers. `markdown-it`
+provides 2 possible stategies, to produce safe output:
+
+1. Don't enable HTML. Extend markup features with [plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin). We think it's the best choice and use it by default.
+   - That's ok for 99% of user needs.
+   - Output will be safe without sanitizer.
+2. Enable HTML and use external sanitizer package.
+
+Also by default `markdown-it` prohibits some kind of links, which could be used
+for XSS:
+
+- `javascript:`, `vbscript:`
+- `file:`
+- `data:`, except some images (gif/png/jpeg/webp).
+
+So, by default `markdown-it` should be safe. We care about it.
+
+If you find a security problem - contact us via tracker or email. Such reports
+are fixed with top priority.
+
+
+## Plugins
+
+Usually, plugins operate with tokenized content, and that's enougth to provide
+safe output.
+
+But there is one non-evident case you should know - don't allow plugins to
+generate arbitrary element `id` and `name`. If those depend on user input -
+always add prefixes to avoid DOM clobbering. See [discussion](https://github.com/markdown-it/markdown-it/issues/28) for details.
+
+So, if you decide to use plugins, adding extended classes syntax or
+autogenerating headers anchors - be careful.

lib/index.js

@@ -22,8 +22,9 @@ var config = {
 
 ////////////////////////////////////////////////////////////////////////////////
 //
-// This validator does not pretend to functionality of full weight sanitizers.
-// It's a tradeoff between default security, simplicity and usability.
+// This validator can prohibit more than really needed to prevent XSS. It's a
+// tradeoff to keep code simple and to be secure by default.
+//
 // If you need different setup - override validator method as you wish. Or
 // replace it with dummy function and use external sanitizer.
 //