docs: re-organize wiki pages, see #159

Basic-Usage.md

@@ -1,23 +0,0 @@
-Render a template string with a context:
-
-```javascript
-var Liquid = require('liquidjs');
-var engine = new Liquid();
-
-engine
-    .parseAndRender('{{name | capitalize}}', {name: 'alice'})
-    .then(console.log);     // outputs 'Alice'
-```
-
-Parsed template can be cached:
-
-```javascript
-// cache the parsed tpl
-var tpl = engine.parse('{{name | capitalize}}');
-
-engine
-    // render the cached tpl with a scope
-    .render(tpl, {name: 'alice'})
-    .then(console.log);     // outputs 'Alice'
-```
-

Builtin-Tags.md

@@ -21,5 +21,5 @@ Tag | Document | Source | Test
 `raw` | [Document](https://help.shopify.com/themes/liquid/tags/theme-tags#raw) | [Source](/harttle/liquidjs/blob/master/src/builtin/tags/raw.ts) | [Test](/harttle/liquidjs/blob/master/test/unit/tags/raw.ts)
 `comment` | [Document](https://help.shopify.com/themes/liquid/tags/theme-tags#comment) | [Source](/harttle/liquidjs/blob/master/src/builtin/tags/comment.ts) | [Test](/harttle/liquidjs/blob/master/test/unit/tags/comment.ts)
 `include` | [Document](https://help.shopify.com/themes/liquid/tags/theme-tags#include) | [Source](/harttle/liquidjs/blob/master/src/builtin/tags/include.ts) | [Test](/harttle/liquidjs/blob/master/test/unit/tags/include.ts)
-`layout, block` | [Document](http://docs.mixture.io/templates/) | [Source](/harttle/liquidjs/blob/master/src/builtin/tags/layout.ts) | [Test](/harttle/liquidjs/blob/master/test/unit/tags/layout.ts)
+`layout, block` | [Document](https://help.shopify.com/en/themes/liquid/tags/theme-tags#layout) | [Source](/harttle/liquidjs/blob/master/src/builtin/tags/layout.ts) | [Test](/harttle/liquidjs/blob/master/test/unit/tags/layout.ts)
 

Caching.md

@@ -0,0 +1,46 @@
+In a typical website project, we'll have a directory of view templates and they'll be rendered multiple times. In production environment the template files are not likely to be changed overtime (other than re-deployments). Thus it's a waste of time to repeatedly read from file system and parse the template string each time. LiquidJS provides multiple ways to cache the parsed templates to improve performance.
+
+## Programmaticly
+
+The [parse][parse], [parseFile][parseFile], [parseFileSync][parseFileSync] APIs are used to parse templates from string or files. The result template can be then rendered multiple times with different context.
+
+Parse from string:
+
+```javascript
+var tpl = engine.parse('{{name | capitalize}}');
+
+engine.renderSync(tpl, {name: 'alice'}) // 'Alice'
+engine.renderSync(tpl, {name: 'bob'}) // 'Bob'
+```
+
+Parse from file:
+
+```javascript
+var tpl = engine.parseFileSync('hello');    // contents of `hello.liquid`: {{name}}
+
+engine.renderSync(tpl, {name: 'alice'}) // 'Alice'
+engine.renderSync(tpl, {name: 'bob'}) // 'Bob'
+```
+
+## The `cache` Option
+
+The [cache option][cache] can be set to instruct liquidjs to use cached parsed templates each time you call [renderFile][renderFile] or [renderFileSync][renderFileSync].
+
+```javascript
+var { Liquid } = require('liquidjs');
+var engine = new Liquid({
+    cache: true
+});
+
+// liquidjs parses the hello.liquid, then renders it with {name: 'alice'}
+engine.renderFileSync('hello', {name: 'alice'})
+
+// liquidjs finds the cached template, then renders it with {name: 'bob'}
+engine.renderFileSync('hello', {name: 'bob'})
+```
+
+[parse]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#parse
+[parseFile]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#parsefile
+[parseFileSync]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#parsefilesync
+[renderFile]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#renderfile
+[renderFileSync]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#renderfilesync

Home.md

@@ -1 +1,66 @@
-Welcome to the liquidjs wiki!
+Welcome to the liquidjs wiki! Liquidjs is a shopify compatible Liquid template engine in pure JavaScript. The purpose of this repo is to provide a standard Liquid implementation for the JavaScript community.
+
+## Get Started
+
+Install via npm:
+
+```bash
+npm install --save liquidjs
+```
+
+```javascript
+var { Liquid } = require('liquidjs');
+var engine = new Liquid();
+
+engine
+    .parseAndRender('{{name | capitalize}}', {name: 'alice'})
+    .then(console.log);     // outputs 'Alice'
+```
+
+Or include the UMD build, a live demo is available on jsfiddle: <https://jsfiddle.net/x43eb0z6/>. You may need a [Promise polyfill][pp] for Node.js &lt; 4 and ES5 browsers like [IE and Android UC][caniuse-promises].
+
+```html
+<script src="//unpkg.com/liquidjs/dist/liquid.min.js"></script>     <!--for production-->
+<script src="//unpkg.com/liquidjs/dist/liquid.js"></script>         <!--for development-->
+```
+
+Also available from CLI:
+
+```bash
+echo '{{"hello" | capitalize}}' | npx liquidjs
+```
+
+## More Demos
+
+There's [a live demo][jsfiddle] on JSFiddle, and a list of demo projects in [the demo/ directory][demo-dir]
+
+* [JSFiddle][jsfiddle]
+* [Demo for Node.js](/harttle/liquidjs/blob/master/demo/node/)
+* [Demo in TypeScript](/harttle/liquidjs/blob/master/demo/typescript/)
+* [Demo for Browser Usage](/harttle/liquidjs/blob/master/demo/browser/)
+* [Demo for Express.js Usage](/harttle/liquidjs/blob/master/demo/express/)
+* [Demo for ReactJS Usage](/harttle/liquidjs/blob/master/demo/reactjs/)
+
+## Documentation
+
+The tutorials contains a list of articles for advanced use cases, performance optimization and extending liquidjs.
+
+* [Render a Template File](/harttle/liquidjs/wiki/Render-a-File)
+* [Caching](/harttle/liquidjs/wiki/Caching)
+* [Use with Express.js](/harttle/liquidjs/wiki/Use-with-Expressjs)
+* [Partials and Layouts](/harttle/liquidjs/wiki/Partials-and-Layouts)
+* [Whitespace Control](/harttle/liquidjs/wiki/Whitespace-Control)
+* [Register Filters/Tags](/harttle/liquidjs/wiki/Register-Filters-Tags)
+* [Plugins](/harttle/liquidjs/wiki/Plugins)
+* [Migrate to 9.0.0](/harttle/liquidjs/wiki/Migrate-to-9)
+
+The [API Reference](https://harttle.github.io/liquidjs/classes/_liquid_.liquid.html) provides detailed descriptions for classes, methods and properties.
+
+* [Options](https://harttle.github.io/liquidjs/interfaces/_liquid_options_.liquidoptions.html)
+* [Builtin Filters](/harttle/liquidjs/wiki/Builtin-Filters)
+* [Builtin Tags](/harttle/liquidjs/wiki/Builtin-Tags)
+* [Operators](/harttle/liquidjs/wiki/Operators)
+* [Truthy and Falsy](/harttle/liquidjs/wiki/Truthy-and-Falsy)
+
+[jsfiddle]: https://jsfiddle.net/x43eb0z6/
+[demo-dir]: https://github.com/harttle/liquidjs/tree/master/demo

Plugins.md

@@ -1,7 +1,7 @@
 A number of tags and filters can be encapsulated into a **plugin**, which will be typically installed via npm.
 This article provides information about how to create and use a plugin
 
-## A Simple Plugin
+## Write a Plugin
 
 We'll make a plugin to upper case every letter of the input,
 save the following snippet to `upup.js`:
@@ -17,7 +17,7 @@ module.exports = function (Liquid) {
 }
 ```
 
-## Introduce a Plugin
+## Use a Plugin
 
 Simply pass the plugin function into the `.plugin()` method:
 
@@ -38,3 +38,5 @@ Since this library excludes certain features that are available on the Shopify p
 
 * Sections Tags (WIP): https://github.com/harttle/liquidjs-section-tags
 * Color Filters: https://github.com/harttle/liquidjs-color-filters
+
+> Feel free to add yours, this file is publicly editable.

Render-a-File.md

@@ -1,4 +1,19 @@
-To render a file, you need to specify a root directory and call the `renderFile` method:
+For a typical project there could be a directory of template files, you'll need to set the [template root][root] and call [renderFile][renderFile] or [renderFileSync][renderFileSync] to render a specific file.
+
+## Render a File
+
+For example you have a directory of templates like this:
+
+```
+.
+├── index.js
+└── views/
+  ├── hello.liquid
+  └── world.liquid
+```
+
+`hello.liquid` contains a single line `name: {{name}}`.
+Now save the following contents into `index.js`:
 
 ```javascript
 var engine = new Liquid({
@@ -9,3 +24,30 @@ engine
     .renderFile("hello", {name: 'alice'})   // will read and render `views/hello.liquid`
     .then(console.log)  // outputs "Alice"
 ```
+
+Run `node index.js` and you'll get output like this:
+
+```
+> node index.js
+name: alice
+```
+
+## Template Lookup
+
+Template files names passed to [renderFile][renderFile], [parseFile][parseFile], [renderFileSync][renderFileSync], [parseFileSync][parseFileSync] APIs,
+and [include][include], [layout][layout] tags are resolved against [the root option][root].
+
+It can be a string-typed path (see above example), or a list of root directories, in which case templates will be looked up in that order. e.g.
+
+```javascript
+var engine = new Liquid({
+    // relative paths will be resolved against `pwd`
+    root: ['views/', 'views/partials/']
+});
+```
+
+[layout]: https://help.shopify.com/en/themes/liquid/tags/theme-tags#layout
+[include]: https://help.shopify.com/themes/liquid/tags/theme-tags#include
+[renderFile]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#renderfile
+[renderFileSync]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#renderfilesync
+[root]: https://harttle.land/liquidjs/interfaces/_liquid_options_.liquidoptions.html#root

Use-with-Expressjs.md

@@ -1,13 +1,64 @@
-LiquidJS is compatible to the [express template engines](https://expressjs.com/en/resources/template-engines.html):
+LiquidJS is compatible to the [express template engines](https://expressjs.com/en/resources/template-engines.html). You can set liquidjs instance to the [view engine][express-views] option:
 
 ```javascript
+var { Liquid } = require('liquidjs');
+var engine = new Liquid();
+
 // register liquid engine
 app.engine('liquid', engine.express()); 
 app.set('views', './views');            // specify the views directory
 app.set('view engine', 'liquid');       // set liquid to default
 ```
 
-[`views`][express-views] variable in express.js will also be respected
+## Template Lookup
-for partial (includes and layouts) look up.
 
+The [root][root] option will continue to work as templates root, as you can see in [Render A Template File][render-a-file]. Additionally, the [`views`][express-views] option in express.js (as shown above) will also be respected. Say you have a template directory like:
+
+```
+.
+├── views1/
+│ └── hello.liquid
+└── views2/
+  └── world.liquid
+```
+
+And you're setting template root for liquidjs to `views1` and expressjs to `views2`:
+
+```javascript
+var { Liquid } = require('liquidjs');
+var engine = new Liquid({
+    root: './views1/'
+});
+
+app.engine('liquid', engine.express()); 
+app.set('views', './views2');            // specify the views directory
+app.set('view engine', 'liquid');       // set liquid to default
+```
+
+Both of `hello.liquid` and `world.liquid` can be resolved and rendered:
+
+```
+res.render('hello')
+res.render('world')
+```
+
+## Caching
+
+Simply setting the [cache option][cache] to true will enable template caching, as explained in [Caching][Caching]. It's recommended to enable cache in production environment, which can be done by:
+
+```javascript
+var { Liquid } = require('liquidjs');
+var engine = new Liquid({
+    cache: process.env.NODE_ENV === 'production'
+});
+```
+
+[cache]: https://harttle.land/liquidjs/interfaces/_liquid_options_.liquidoptions.html#cache
 [express-views]: http://expressjs.com/en/guide/using-template-engines.html
+[parseFile]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#parsefile
+[parseFileSync]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#parsefilesync
+[layout]: https://help.shopify.com/en/themes/liquid/tags/theme-tags#layout
+[include]: https://help.shopify.com/themes/liquid/tags/theme-tags#include
+[root]: https://harttle.land/liquidjs/interfaces/_liquid_options_.liquidoptions.html#root
+[render-a-file]: /harttle/liquidjs/wiki/Render-a-File
+[Caching]: /harttle/liquidjs/wiki/Caching

_Sidebar.md

@@ -1,22 +1,16 @@
 * [Home](/harttle/liquidjs/wiki)
 * Tutorial
-    * [Basic Usage](/harttle/liquidjs/wiki/Basic-Usage)
+    * [Render a Template File](/harttle/liquidjs/wiki/Render-a-File)
-    * [Render a File](/harttle/liquidjs/wiki/Render-a-File)
+    * [Caching](/harttle/liquidjs/wiki/Caching)
     * [Use with Express.js](/harttle/liquidjs/wiki/Use-with-Expressjs)
     * [Partials and Layouts](/harttle/liquidjs/wiki/Partials-and-Layouts)
     * [Whitespace Control](/harttle/liquidjs/wiki/Whitespace-Control)
     * [Register Filters/Tags](/harttle/liquidjs/wiki/Register-Filters-Tags)
-    * [Write a Plugin](/harttle/liquidjs/wiki/Write-a-Plugin)
+    * [Plugins](/harttle/liquidjs/wiki/Plugins)
     * [Migrate to 9.0.0](/harttle/liquidjs/wiki/Migrate-to-9)
-* API
+* [API](https://harttle.github.io/liquidjs)
     * [Options](https://harttle.github.io/liquidjs/interfaces/_liquid_options_.liquidoptions.html)
     * [Builtin Filters](/harttle/liquidjs/wiki/Builtin-Filters)
     * [Builtin Tags](/harttle/liquidjs/wiki/Builtin-Tags)
     * [Operators](/harttle/liquidjs/wiki/Operators)
     * [Truthy and Falsy](/harttle/liquidjs/wiki/Truthy-and-Falsy)
-* Demos
-    * [Node.js Demo](demo/node/)
-    * Browser: [jsfiddle](https://jsfiddle.net/6u40xbzs/), [/demo/browser/](/harttle/liquidjs/blob/master/demo/browser/)
-    * [Express.js Demo](/harttle/liquidjs/blob/master/demo/express/)
-    * [TypeScript Demo](/harttle/liquidjs/blob/master/demo/typescript/)
-    * [React JS Demo](/harttle/liquidjs/blob/master/demo/reactjs/)