Rewrite section

README.md

@@ -39,19 +39,37 @@ More examples in [the wiki](https://github.com/erusev/parsedown/wiki/) and in [t
 ### Security
 
 Parsedown is capable of escaping user-input within the HTML that it generates.
-Additionally Parsedown can attempt to sanitize additional scriping vectors (such
+Additionally Parsedown will apply sanitisation to additional scripting vectors (such
-as scripting link destinations). To tell Parsedown that it is processing untrusted
+as scripting link destinations) that are introduced by the markdown syntax itself.
-user input, use the following:
+To tell Parsedown that it is processing untrusted user-input, use the following:
 ```php
 $parsedown = new Parsedown;
 $parsedown->setSafeMode(true);
 ```
 
-It is recommended that when you deal with untrusted content (ex: user comments)
+If instead, you wish to allow HTML within untrusted user input, but still want
-you should employ defense-in-depth measures, like making use of a HTML sanitizer
+output to be free from XSS it is recommended that you make use of a HTML sanitiser
 that allows HTML tags to be whitelisted, like [HTML Purifier](http://htmlpurifier.org/).
-Additionally, you should strongly consider 
+
-[deploying a Content-Secuity-Policy](https://scotthelme.co.uk/content-security-policy-an-introduction/).
+In both cases you should strongly consider employing defence-in-depth measures, 
+like [deploying a Content-Secuity-Policy](https://scotthelme.co.uk/content-security-policy-an-introduction/)
+(making use of browser security feature) so that your page is likely to be safe even if an
+attacker finds a vulnerability in one of the first lines of defence above.
+
+#### Security of Parsedown Extensions
+
+Safe mode does not necessarily yield safe results when using extensions to Parsedown. Extensions should be evaluated on their own to determine their specific safety against XSS.
+
+### Escaping HTML
+> ⚠️  **WARNING:** This method isn't safe from XSS!
+
+If you wish to escape HTML **in trusted input**, you can use the following:
+```php
+$parsedown = new Parsedown;
+$parsedown->setMarkupEscaped(true);
+```
+
+Beware that this still allows users to insert unsafe scripting vectors, such as links like `[xss](javascript:alert%281%29)`.
 
 ### Questions