From 83b27b3344a7d5ab7b58eb1ada1f9aafaac8a717 Mon Sep 17 00:00:00 2001
From: Floriel Fedry <Ffloriel@users.noreply.github.com>
Date: Sun, 16 Jul 2017 21:59:36 +0200
Subject: [PATCH] Update Readme

- Table of content
- What is purgecss?
- Differences with
---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/README.md b/README.md
index 28f1c64d..0d414c07 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,27 @@
 </p>
 
 
+- [What is purgecss?](#what-is-purgecss)
+- [Getting started](#getting-started)
+- [Usage](#usage)
+- [Build plugin](#build-plugin)
+- [CLI](#cli)
+- [Differences with](#differences-with)
+- [Contributing](#contributing)
+
+
+## What is purgecss?
+
+Purgecss is a tool inspired by Purifycss to remove unused css. Originally thought as the v2 of purifycss,
+purgecss has for goal to act in a similar way while correcting the known ploblems of purifycss. If you want
+to know more about the differences between purifycss and purgecss, go to the section [Differences with](#differences-with).  
+When you are building a website, chances are that you are using a css framework. Bootstrap, Materializecss, Foundation are
+some of the big css framework that you can include to your website, but you will only use a small set of the framework and
+a lot of unused css styles will be included.  
+This is where Purgecss comes into play. Purgecss takes your content and your css and matches the selectors used in your files
+with the one in your content files. It removes every unused selectors from your css files, resulting in smaller, optimize css
+files.
+
 ### Getting Started
 
 #### Installation
@@ -104,6 +125,39 @@ Options:
   -v, --version     Show version number                                [boolean]
 ```
 
+### Differences with
+
+#### Purifycss
+
+The biggest flaw with purifycss is its lack of modularity. It is also is biggest benefit, purifycss can work with any files,
+not just html or javascript. But purifycss works by looking at all the words in the files and comparing them with the selectors
+in the css. Every words is consider a selector, which means that a lot of selectors can be consider used because you have the
+selector name in a paragraph or somewhere in your files.
+
+Purgecss fixes this problem by providing the possibility to create an _extractor_, an extractor is a function that takes the content
+of a file and extract the list of css selectors in it. It allows a perfect removal of unused css. The extractor can used a parser
+that returns an ast and then looks through it to select the css selectors. That is the way `purge-from-html` works.
+You can specified which selectors you want to use for each types of files, and so, get the most accurate results.
+You can still use the default or the legacy extractor that will act the same way as purifycss.
+
+#### Uncss
+
+As indicated in its Readme, Uncss works the following way:
+1. The HTML files are loaded by jsdom and JavaScript is executed.
+2. All the stylesheets are parsed by PostCSS.
+3. document.querySelector filters out selectors that are not found in the HTML files.
+4. The remaining rules are converted back to CSS.
+
+Because of the emulation of html, and the execution of javascript, uncss is effective at removing unused selectors from web application.
+But the emulation can have a cost in term of performance and practicality. Uncss works by emulating the html files. To remove unused css
+from pug template files, you will need to convert pug to html and then emulate the page inside jsdom and uncss will run `document.querySelector`
+on each selectors and step 4.  
+Uncss by its design is probably the most accurate tool to remove css out of a web application at this moment.  
+
+Purgecss does not have an extractor right now for javascript files. But because of its modularity, developers can create an extractor for specific
+framework (vue, react, aurelia) and files (pug, ejs) and get the most accurate result without the need of emulation.
+
+
 ## Contributing
 
 Please read [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.