From 90439ef882500d98f581e725833bec370ece6bb2 Mon Sep 17 00:00:00 2001
From: Aidan Woods <aidantwoods@gmail.com>
Date: Thu, 1 Mar 2018 18:44:11 +0000
Subject: [PATCH] Rewrite section

---
 README.md | 32 +++++++++++++++++++++++++-------
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 68f216e..9bc3657 100644
--- a/README.md
+++ b/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
-as scripting link destinations). To tell Parsedown that it is processing untrusted
-user input, use the following:
+Additionally Parsedown will apply sanitisation to additional scripting vectors (such
+as scripting link destinations) that are introduced by the markdown syntax itself.
+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)
-you should employ defense-in-depth measures, like making use of a HTML sanitizer
+If instead, you wish to allow HTML within untrusted user input, but still want
+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