diff --git a/README.md b/README.md
index 6822623da..64fcf9b7e 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,134 @@
[](https://www.npmjs.com/package/marko)
[](http://npm-stat.com/charts.html?package=marko)
-Marko is a fast and lightweight HTML-based templating engine that compiles templates to CommonJS modules and supports streaming, async rendering and custom tags. Learn more on [http://markojs.com/](http://markojs.com/).
+Marko is a [_really_ fast](https://github.com/marko-js/templating-benchmarks) and lightweight HTML-based templating engine that compiles templates to CommonJS modules and supports streaming, async rendering and custom tags. Learn more on [http://markojs.com/](http://markojs.com/).
+
+You can try out Marko online: [Try Marko Online!](http://markojs.com/try-online/)
+
+# Installation
+
+```bash
+npm install marko --save
+```
+
+# Syntax
+
+Marko supports _both_ a familiar HTML syntax, as well as a more concise indentation-based syntax. Both syntaxes are equally supported. Regardless of which syntax you choose, the compiled code will be exactly the same.
+
+## HTML syntax
+
+```html
+
+
+
+ Marko Templating Engine
+
+
+
+ Hello ${data.name}!
+
+
+
+
+ No colors!
+
+
+
+```
+
+## Concise syntax
+
+The following concise template is equivalent to the previous template:
+
+```html
+
+html lang="en"
+ head
+ title - Marko Templating Engine
+ body
+ h1 - Hello ${data.name}!
+ ul if(notEmpty(data.colors))
+ li for(color in data.colors)
+ ${color}
+ div else
+ - No colors!
+```
+
+## Mixed syntax
+
+You can even mix and match the concise syntax with the HTML syntax within the same document.
+The following template is equivalent to the previous templates:
+
+```html
+
+html lang="en"
+ head
+ title - Marko Templating Engine
+ body
+
+ Hello ${data.name}!
+
+ ul if(notEmpty(data.colors))
+ li for(color in data.colors)
+ ${color}
+ div else
+ - No colors!
+```
+
+# Basic Usage
+
+## Loading a template
+
+```javascript
+var template = require('./template.marko');
+```
+
+NOTE: On the server, you will need to install the Node.js require extension for Marko:
+
+```javascript
+require('marko/node-require').install();
+```
+
+## Rendering a template
+
+```javascript
+var templateData = { name: 'Frank' };
+
+// Render to an existing Writable stream:
+template.render(templateData, process.stdout);
+
+// Render to a callback function:
+template.render(templateData, function(err, html) {
+ console.log(html);
+ });
+
+// Render a template synchronously
+console.log(template.renderSync(templateData));
+
+// Render a template and return a new Readable stream:
+template.stream(templateData).pipe(process.stdout);
+```
+
+# UI Components
+
+Marko Widgets is a minimalist library for building UI components with the help of the
+[Marko templating engine](http://markojs.com/docs/). Marko is used for rendering the HTML for UI components,
+while Marko Widgets is used to add client-side behavior. Client-side behavior includes the following:
+
+- Handling DOM events
+- Emitting custom events
+- Handling custom events emitted by other widgets
+- Manipulating and updating the DOM
+
+Changing a widgets state or properties will result in the DOM automatically being updated without writing extra code. Marko Widgets has adopted many of the good design principles promoted by the [React](https://facebook.github.io/react/index.html) team, but aims to be much lighter and often faster (especially on the server). When updating the view for a widget, Marko Widgets uses DOM diffing to make the minimum number of changes to the DOM through the use of the [morphdom](https://github.com/patrick-steele-idem/morphdom) module.
+
+Try Marko Widgets Online!
+
+For more details on Marko Widgets, please check out the [Marko Widgets Documentation](http://markojs.com/docs/marko-widgets/).
# Changelog