1 files changed, 91 insertions, 0 deletions
diff --git a/doc/UrlFilter.md b/doc/UrlFilter.md
new file mode 100644
index 0000000..cea2397
--- /dev/null
+++ b/doc/UrlFilter.md
@@ -0,0 +1,91 @@
+## FilterDomain
+Filter Domains are groups of domains that can point to one or more filter
+rules.
+
+### Types
+There are 4 Filter Domain types:
+- AllowOnDomains - only match specified domains
+- BlockOnDomains - match all but specified domains
+- AllowOnAllDomains - match all domains
+- BlockOnAllDomains - match no domains
+
+### JSON
+    {
+        "type" : "AllowOnDomains",
+        "domains" : [ "example.com", "test.example.com" ],
+        "rules" : []
+    }
+
+## FilterRule
+Filter rules contain information on how a request should be modified.
+
+### "action"
+- Whitelist - allow this request
+- Blacklist - block this request
+- Redirect - redirect this request
+- SetHeader - apply a list of headers
+
+### "regexp", "contains", "endswith"
+
+### JSON
+Allow all URLs that contain "waifu.png"
+    {
+        "action" : "Whitelist"
+        "contains" : "waifu.png"
+    }
+
+Block specific URL
+    {
+        "action" : "Blacklist"
+        "equals" : "example.com/annoying-ad/masquerade/waifu.png"
+    }
+
+Block all URLs that contain "banner.gif"
+    {
+        "action" : "Blacklist",
+        "contains" : "banner.gif"
+    }
+
+Redirect URLs containing "ads/annoying-spam.gif" to "waifu.tld/waifu.gif"
+    {
+        "action" : "Redirect"
+        "contains" : "ads/annoying-spam.gif"
+        "url" : "waifu.tld/waifu.gif"
+    }
+
+Set some headers
+    {
+        "action" : "SetHeader"
+        "header" : [ "DNT" : "1" ]
+    }
+
+## QWebEngineUrlRequestInterceptor
+
+All network requests pass through the request interceptor. It gives the
+following information:
+
+- firstPartyUrl - the page on which the request is made
+- requestUrl - the url of the request
+- requestMethod
+- resourceType
+- navigationType
+
+And provides the following methods:
+
+- block (bool shouldBlock) - can block the request
+- redirect (const QUrl) - can redirect the requestUrl
+- setHttpHeader - can set HTTP headers (such as user agent and do not track)
+
+### Example
+This is a sample request made when loading DuckDuckGo:
+
+    firstPartyUrl=https://duckduckgo.com/
+    requestUrl=https://duckduckgo.com/o1635.css
+
+## How the filter works
+When a requst comes in, the interceptor extracts the host of the request and
+matches it against the list of FilterDomains.
+
+    firstPartyHost=duckduckgo.com
+    requestHost=duckduckgo.com
+