Merge pull request linkedin#23 from prashn64/doc-pages

Make the about page the homepage, and fix some markdown

_includes/nav.md

@@ -5,7 +5,7 @@
     <h2 class="tagline">Asynchronous templates for the browser and nodejs</h2>
   </header>
   <ul class="main-nav">
-    <li><a href="/about">About</a></li>
+    <li><a href="/">About</a></li>
     <li>
       Guides
       <ul>
@@ -14,7 +14,6 @@
       <li><a href="/guides/dust-helpers">Dust Helpers</a></li>
       <li><a href="/guides/using-filters">Using Filters</a></li>
       <li><a href="/guides/partials">Partials</a></li>
-      <li><a href="/guides/layouts">Layouts</a></li>
       <li><a href="/guides/base-and-override-templates">Base and override templates</a></li>
       <li><a href="/guides/tips-and-tricks">Tips and Tricks</a></li>
       <li><a href="/guides/advanced-topics">Advanced Topics</a></li>

docs/api.md

@@ -5,13 +5,16 @@ permalink: /docs/api/
 ---
 
 ## dust.compile
+
 ### Function call
 ```    
 dust.compile(content, templateName);
 ```
+
 ### Parameters
 * content {String}: The content of your dust template.
 * templateName {String}: The name under which the template will be registered.  This is the name you will use when rendering the template.
+
 ### Return Value
 * {String} Template compiled to JavaScript.
 
@@ -41,13 +44,15 @@ If you include the "compiled" output as part of a script block of JS that you lo
 All of these compiled templates are saved in the dust.cache Array under the name they were registered under, in this case, "intro".
 
 ## dust.loadSource
+
 ### Function call
 ```
 dust.loadSource(compiledOutput);
 ```
 
 ### Parameters
 * compiledOutput {String}: The compiled dust template
+
 ### Return Value
 * {Void}
 
@@ -59,10 +64,12 @@ dust.loadSource(compiledTemplate);
 ```
 
 ## dust.render
+
 ### Function call
 ```
 dust.render(templateName, data, callback);
 ```
+
 ### Parameters
 * templateName {String}: The registered name of the template to render.  This was the name given to the template at the compilation step.
 * data {Object}: The data to be used to populate the template.
@@ -72,6 +79,7 @@ dust.render(templateName, data, callback);
         * output {String} Contains the full output of the rendered template.  If error is non-empty, output will be empty.
     * **Return Value**
         * {Void}
+
 ### Return Value
 {Void}
 
@@ -89,16 +97,19 @@ dust.render("intro", {name: "Fred"}, function(error, output) {
 ```
 
 ## dust.stream
+
 ### Function call
 ```    
 var stream = dust.stream(templateName, data);
 stream.on('data', dataCallback)
       .on('end', endCallback)
       .on('error', errorCallback);
 ```
+
 ### Parameters
 * templateName {String}: The registered name of the template to render.  This was the name given to the template at the compilation step.
 * data {Object}: The javascript context to be used to populate the template.
+
 ### Return Value
 * {Stream} An object that can be used to attach event callbacks to.
 

index.md

@@ -2,3 +2,69 @@
 title: DustJS by LinkedIn
 layout: default
 ---
+
+# What is Dust?
+
+Dust is a Javascript templating engine. It inherits its look from the [ctemplate](https://code.google.com/p/ctemplate/) family of languages, and is designed to run asynchronously on both the server and the browser.
+
+# Why Dust?
+
+This overview won't tell you about all the features Dust has to offer. Instead, we'll focus on some of the differentiators between Dust and other Javascript templating languages.
+
+## Not logicless... just less logic
+
+You cannot write arbitrary Javascript inside Dust templates. However, you still have basic logical operators like comparison, less than / greater than, and exists / not exists. This strikes a balance between template readability and data control.
+
+Instead, Dust encourages you to move the logic to your data model. You can create functions inside the model that are then called by the template, giving you complete control over how your templates render without cluttering them with logic.
+
+So instead of this:
+
+```
+{@eq key="userExists" value="true"}
+  {@eq key="passwordOK" value="true"}
+    {@gt key="userLevel" value=3}
+      {@eq key="accountActive" value="true"}
+        Welcome!
+      {/eq}
+    {/gt}
+  {/eq}
+{/eq}
+```
+
+Dust encourages you to write this:
+
+```
+{#userAuthenticated}
+  Welcome!
+{/userAuthenticated}
+```
+
+## Asynchronous template loading, rendering, and streaming
+
+Dust can load and render templates on-the-fly, so you don't have to preload them. For example, instead of concatenating all templates into a file that's loaded via a `<script>` tag, you might choose to asynchronously load templates as they're requested. Or, if you're using Dust in Node, you could load templates from the filesystem, read them from an in-memory cache, or compile them just-in-time.
+
+In addition, while Dust is waiting to load a template, it can continue rendering the rest of the page asynchronously. After loading is complete, the missing template will be seamlessly added.
+
+This asynchronous rendering isn't limited to waiting for templates. If you make HTTP requests to an external data source, Dust will continue to render the template while it waits for the request to complete.
+
+Finally, Dust has a Node Streams-compliant interface to allow you to pipe its output incrementally. So, you can flush the output of a large template piece-by-piece to the browser to reduce the time the user stares at a blank screen.
+
+## Composable templates
+
+You shouldn't have to manually build layouts in code-- that information belongs in your templates. Dust supports partial includes and dynamic template blocks so that you can write simple templates and stitch them together however you want.
+
+## HTML-safe, format-agnostic
+
+It's likely that you're using Dust to render HTML. Dust helps you out by safely escaping data, preventing cross-site scripting attacks. Filters are also included for Javascript and JSON output, and you can add your own filters easily.
+
+Dust doesn't force you to output HTML, though. It works just as well to generate any number of formats, such as Markdown, JSON, or YAML.
+
+## High performance
+
+Dust attempts to strike a balance between performance and features. While it's not as fast as a truly logicless templating system like Mustache, its asynchronous nature means that it will start rendering large templates more quickly.
+
+Dust can precompile your templates for even more speed, or dynamically load them so that you don't take the up-front performance hit of loading a bunch of templates that you'll never use. (Or, preload a subset of templates and dynamically load the rest. You can do that too.)
+
+## Widely-supported
+
+Dust works where Javascript works. You can use Dust as far back as IE7, as well as on the server using Node, io.js, Rhino, or Nashorn.