diff --git a/README.md b/README.md
index 86a8bcb..7786994 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,9 @@
-# thumbsup
+
+```
+┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐
+│ t │ │ h │ │ u │ │ m │ │ b │ │ s │ │ u │ │ p │
+└───┘ └───┘ └───┘ └───┘ └───┘ └───┘ └───┘ └───┘
+```
 
 [![NPM](http://img.shields.io/npm/v/thumbsup.svg?style=flat)](https://npmjs.org/package/thumbsup)
 [![License](http://img.shields.io/npm/l/thumbsup.svg?style=flat)](https://github.com/rprieto/thumbsup)
@@ -12,21 +17,37 @@ Build static HTML galleries from local photos & videos.
 - uses relative paths so you can deploy the pages anywhere
 - works great with Amazon S3 for static hosting
 
-[View sample website](http://rprieto.github.io/thumbsup)
+## Table of contents
 
-[![screenshot](https://raw.github.com/rprieto/thumbsup/master/screenshot.jpg)](http://rprieto.github.io/thumbsup)
+<!-- START toc -->
+- [Table of contents](#table-of-contents)
+- [Example gallery](#example-gallery)
+- [Required folder structure](#required-folder-structure)
+- [Setup](#setup)
+  * [As an npm package](#as-an-npm-package)
+- [Expected output](#expected-output)
+- [Configuration](#configuration)
+- [Generated gallery structure](#generated-gallery-structure)
+- [Deployment](#deployment)
+- [Password protection](#password-protection)
+- [Dev notes](#dev-notes)
+<!-- END toc -->
 
-## Requirements
+## Example gallery
 
-- [Node.js](http://nodejs.org/): `brew install Node`
-- [GraphicsMagick](http://www.graphicsmagick.org/): `brew install graphicsmagick`
-- [FFmpeg](http://www.ffmpeg.org/): `brew install ffmpeg`
+You can [view a sample gallery here](http://rprieto.github.io/thumbsup).
+The home/index page shows all folders, with a few stats and some previews:
 
-*Note: there currently is [an issue with Ubuntu 14.04](#27) if you build `ffmpeg` from source. Please upgrade to 14.10 and install it with `apt-get`.*
+[![screenshot](https://raw.github.com/rprieto/thumbsup/master/screenshot.jpg)](http://rprieto.github.io/thumbsup)
+
+The photo pages are a grid of photos:
+
+[![screenshot](https://raw.github.com/rprieto/thumbsup/master/screenshot.jpg)](http://rprieto.github.io/thumbsup)
 
-## Input
+## Required folder structure
 
-Any folder with photos and videos. `thumbsup` currently supports 1 level of subfolders, where they each become a gallery.
+Any folder with photos and videos!
+`thumbsup` currently supports 1 level of subfolders, where they each become a gallery.
 
 ```
 input
@@ -40,15 +61,33 @@ input
        |__ img003.png
 ```
 
-## Generating the galleries
+## Setup
 
-Install the module globally, which puts the binary in your path:
+### As an npm package
 
+**Requirements**
+
+- [Node.js](http://nodejs.org/): `brew install Node`
+- [GraphicsMagick](http://www.graphicsmagick.org/): `brew install graphicsmagick`
+- [FFmpeg](http://www.ffmpeg.org/): `brew install ffmpeg`
+
+*Note: there currently is [an issue with Ubuntu 14.04](#27) if you build `ffmpeg` from source. Please upgrade to 14.10 and install it with `apt-get`.*
+
+**Installation**
+
+```bash
+npm install -g thumbsup
 ```
-$ npm install -g thumbsup
-```
 
+**Creating a basic gallery**
+
+```bash
+thumbsup --input ~/photos --output ~/gallery
 ```
+
+## Expected output
+
+```bash
 $ thumbsup [args]
 
   List all files      [===================] 6/6 files
@@ -65,6 +104,8 @@ $ thumbsup [args]
   Gallery generated successfully
 ```
 
+## Configuration
+
 The following args are required:
 
 - `--input <path>` path to the folder with photos / videos
@@ -111,7 +152,7 @@ thumbsup --config config.json
 }
 ```
 
-## Website structure
+## Generated gallery structure
 
 The generated static website has the following structure:
 
@@ -148,7 +189,7 @@ An alternative is to deploy the galleries to UUID-based locations, like Dropbox
 
 To create the sample gallery locally:
 
-```
+```bash
 npm run clean      # clean the output
 npm run example    # build the gallery
 npm run open       # open it in the browser
diff --git a/package.json b/package.json
index 27eac7c..db5900b 100644
--- a/package.json
+++ b/package.json
@@ -21,7 +21,8 @@
   "scripts": {
     "clean": "rm -rf _site/*",
     "example": "node bin/thumbsup --config example.json",
-    "open": "open _site/index.html"
+    "open": "open _site/index.html",
+    "readme": "markdown-toc README.md | node-injectmd -t toc -i README.md"
   },
   "bin": {
     "thumbsup": "./bin/thumbsup.js"
@@ -39,5 +40,9 @@
     "pad": "~1.0.0",
     "progress": "~1.1.8",
     "yargs": "^3.32.0"
+  },
+  "devDependencies": {
+    "injectmd": "^1.0.0",
+    "markdown-toc": "^0.12.5"
   }
 }