diff --git a/README.md b/README.md
index dcccc60..bcd03fc 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,264 @@
-[Feather](https://feathericons.com)
-===
+# Feather
-### Simply beautiful open source icons
+## What is Feather?
-Designed on a 24x24 grid with an emphasis on functionality, consistency and simplicity.
+Feather is collection of **simply beautiful open source icons**. Each icon is designed on a 24x24 grid with an emphasis on simplicity, consistency and legibility.
-*Documentation coming soon*
+[feathericons.com](https://feathericons.com)
-Related Projects
----
+## Table of Contents
+
+* [Quick Start](#quick-start)
+* [Usage](#usage)
+ * [Client-side JavaScript](#client-side-javascript)
+ * [Node](#node)
+* [API Reference](#api-reference)
+ * [`feather.icons`](#feathericons)
+ * [`feather.toSvg()`](#feathertosvgkey-options)
+ * [`feather.replace()`](#featherreplaceoptions)
+* [Roadmap](#roadmap)
+* [Contributing](#contributing)
+* [License](#license)
+
+## Quick Start
+
+Start with this [CodePen Template](https://codepen.io/pen?template=WOJZdM) to begin prototyping with Feather in the browser.
+
+Or copy and paste the following code snippet into a blank `html` file.
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## Usage
+
+At its core, Feather is a collection of [SVG](https://svgontheweb.com/#svg) files. This means that you can use Feather icons in all the same ways you can use SVGs (e.g. `img`, `background-image`, `inline`, `object`, `embed`, `iframe`). Here's a helpful article detailing the many ways SVGs can be used on the web: [SVG on the Web – Implementation Options](https://svgontheweb.com/#implementation)
+
+The following are additional ways you can use Feather.
+
+### Client-side JavaScript
+
+#### 1. Install
+
+> **Note:** If you intend to use Feather with a CDN, you can skip this installation step.
+
+Install with [npm](https://docs.npmjs.com/getting-started/what-is-npm).
+
+```
+npm install feather-icons --save
+```
+
+Or just copy [`feather.js`](https://unpkg.com/feather-icons/dist/feather.js) or [`feather.min.js`](https://unpkg.com/feather-icons/dist/feather.min.js) into your project directory. You don't need both `feather.js` and `feather.min.js`.
+
+#### 2. Include
+
+Include `feather.js` or `feather.min.js` with a `
+```
+
+Or load the script from a CDN provider.
+
+```html
+
+```
+
+After including the script, `feather` will be available as a global variable.
+
+#### 3. Use
+
+To use an icon on your page, add a `data-feather` attribute with the icon name to an element.
+
+```html
+
+```
+
+See the complete list of icons at [feathericons.com](https://feathericons.com).
+
+#### 4. Replace
+
+Call the `feather.replace` method.
+
+```html
+
+```
+
+All elements that have a `data-feather` attribute will be replaced with SVG markup corresponding to their `data-feather` attribute value. See the [API Reference](#api-reference) for more information about `feather.replace()`.
+
+### Node
+#### 1. Install
+
+Install with [npm](https://docs.npmjs.com/getting-started/what-is-npm).
+
+```
+npm install feather-icons --save
+```
+
+#### 2. Require
+
+```javascript
+var feather = require('feather-icons')
+```
+
+#### 3. Use
+```javascript
+feather.icons.circle
+//
+
+feather.toSvg('circle')
+// ''
+
+feather.toSvg('circle', { class: 'my-class', 'stroke-width': 1 })
+// ''
+```
+
+See the [API Reference](#api-reference) for more information about the available properties and methods of the `feather` object.
+
+### Sprite
+
+*Coming soon*
+
+## API Reference
+
+### `feather.icons`
+
+An object with SVG path information for every icon.
+
+#### Usage
+
+```javascript
+feather.icons.circle
+//
+
+feather.icons.clock
+// ''
+```
+
+### `feather.toSvg(key, [options])`
+
+Returns an SVG string.
+
+#### Parameters
+
+| Name | Type | Description |
+| --------- | ------ | ----------- |
+| `key` | string | Icon name |
+| `options` (optional) | Object | Key-value pairs in the `options` object will be mapped to HTML attributes on the `