docs: updates readme with some more info

Author: mdarrik

README.md

@@ -1,5 +1,19 @@
-# Netlify Plugin CSP Hash
+# Netlify Plugin CSP Headers
+
+Add strict Content Security Policy (CSP) headers to your site.
+
+While static sites are fairly secure, there's still a risk of Cross Site Scripting and other malicious attacks affecting your users. Having a solid Content Security Policy can help mitigate those risks further. 
+
+CSP Headers can also help you get better scores on some automated tests, like [Web Page Test](https://www.webpagetest.org/)
+
+
+## Warning about Netlify Asset Optimizations
+
+To improve the security of inline script & style tags, it takes a hash of the contents. This can stop attackers from modifying them after you've deployed your site. It also prevents new ones from being added. However, this also means that Netlify's Asset Optimization can break your site. Because Asset Optimization changes the URLs of static assets like fonts after your build is complete, it makes the hashes no longer match the ones generated by this plugin. This causes your browser to block those inline assets. Unfortunately, I haven't come up with a good way around this since the URLs are randomly generated. Unfortunately, even if you only use the Pretty URLs optimization, self hosted font urls will still get replaced. To get around this, I currently see 3 options: 
+
+1. Move all `<style>` tags with font declarations to an external file. This will add additional network requests to your page load, and may cause performance to drop slightly. 
+1. Turn off all optimizations (including pretty urls 😢). This will stop Netlify from changing anything about your code. You'll also be responsible for optimizing all of your own assets. It may also prevent "pretty urls" from working correctly on your site (so pages might be at `https://example.com/route/index.html` instead of `https://example.com/route/`). 
+1. Add the environment variable `CSP_HEADERS_UNSAFE_STYLE` with a value of `true` in your Netlify UI Dashboard. The plugin will then not include any hashes for style tags in the CSP headers. This is probably mostly safe. However, there are some risks of malicious `<style>` elements, especially around images. 
+
 
-This plugin hashes your script & style files & adds the hashes to Content Security Policies. This helps protect your users from malicious actors modifying your scripts. 
 
-Future versions may allow you to exclude user-provided content as a way to add an extra layer of security.