diff --git a/README.md b/README.md
index 13c6809..5ab95e5 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,35 @@
-# express-fileupload
-Simple express file upload middleware that wraps around [connect-busboy](https://github.com/mscdex/connect-busboy).
+# Description
+Simple express middleware for uploading files.
-## Install
+# Install
```bash
-npm install express-fileupload
-```
+# With NPM
+npm install --save express-fileupload
-## Important Note
-Add `app.use(fileUpload())` *AFTER* `app.use(bodyParser.json)` and any other bodyParser middlewares! This limitation will be explored and resolved in an upcoming release.
+# With Yarn
+yarn add express-fileupload
+```
-=======
-Pass in Busboy options directly to express-fileupload (using Busboy `v0.2.13`). Check out the Busboy documentation here: https://github.com/mscdex/busboy#api
+# Usage
+When you upload a file, the file will be accessible from `req.files`.
+### Example Scenario
+* You're uploading a file called **car.jpg**
+* Your input's name field is **foo**: ``
+* In your express server request, you can access your uploaded file from `req.files.foo`:
```javascript
-app.use(fileUpload({
- limits: { fileSize: 50 * 1024 * 1024 },
-}));
+app.post('/upload', function(req, res) {
+ console.log(req.files.foo); // the uploaded file object
+});
```
+The **req.files.foo** object will contain the following:
+* `req.files.foo.name`: "car.jpg"
+* `req.files.foo.mv`: A function to move the file elsewhere on your server
+* `req.files.mimetype`: The mimetype of your file
+* `req.files.data`: A buffer representation of your file
-## Example
-
-### Node.js:
-
+### Full Example
+**Your node.js code:**
```javascript
var express = require('express');
var fileUpload = require('express-fileupload');
@@ -31,41 +39,66 @@ var app = express();
app.use(fileUpload());
app.post('/upload', function(req, res) {
- var sampleFile;
-
- if (!req.files) {
- res.send('No files were uploaded.');
- return;
- }
-
- sampleFile = req.files.sampleFile;
- sampleFile.mv('/somewhere/on/your/server/filename.jpg', function(err) {
- if (err) {
- res.status(500).send(err);
- }
- else {
- res.send('File uploaded!');
- }
- });
+ var sampleFile;
+
+ if (!req.files) {
+ res.send('No files were uploaded.');
+ return;
+ }
+
+ // The name of the input field (i.e. "sampleFile") is used to retrieve the uploaded file
+ sampleFile = req.files.sampleFile;
+
+ // Use the mv() method to place the file somewhere on your server
+ sampleFile.mv('/somewhere/on/your/server/filename.jpg', function(err) {
+ if (err) {
+ res.status(500).send(err);
+ }
+ else {
+ res.send('File uploaded!');
+ }
+ });
});
```
-### HTML Form:
+**Your HTML file upload form:**
```html
-
-
-
+
+
+
```
-## Thanks & Credit
+### Using Busboy Options
+Pass in Busboy options directly to the express-fileupload middleware. [Check out the Busboy documentation here.](https://github.com/mscdex/busboy#api)
+
+```javascript
+app.use(fileUpload({
+ limits: { fileSize: 50 * 1024 * 1024 },
+}));
+```
+
+### Available Options
+Pass in non-Busboy options directly to the middleware. These are express-fileupload specific options.
+
+Option | Acceptable Values | Details
+--- | --- | ---
+safeFileNames |
false **(default)**
true
regex
| Strips characters from the upload's filename. You can use custom regex to determine what to strip out. If set to `true`, non-alphanumeric characters _except_ dashes and underscores will be stripped. This option is off by default.
**Example #1 (strip out slashes from file names):** `app.use(fileUpload({ safeFileNames: /\\/g }))` **Example #2:** `app.use(fileUpload({ safeFileNames: true }))`
+
+# Known Bugs
+##### If you're using bodyParser middleware
+Add `app.use(fileUpload())` *AFTER* `app.use(bodyParser.json)` and any other `bodyParser` middlewares! This limitation will be investigated in an upcoming release.
+
+# Help Wanted!
+Pull Requests are welcomed!
-* [Brian White](https://github.com/mscdex) for his stellar work on the [Busboy Package](https://github.com/mscdex/busboy) and the [connect-busboy Package](https://github.com/mscdex/connect-busboy)
+# Thanks & Credit
+[Brian White](https://github.com/mscdex) for his stellar work on the [Busboy Package](https://github.com/mscdex/busboy) and the [connect-busboy Package](https://github.com/mscdex/connect-busboy)