Improve templating documentation

4 files changed, 74 insertions, 8 deletions

diff --git a/docs/config.md b/docs/config.md
index 750f88f..a7484df 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -13,11 +13,11 @@ GitBook allows you to customize your book using a flexible configuration. These
 | `language` | ISO code of the book's language, default value is `en` |
 | `direction` | `rtl` or `ltr`, default value depends on the value of `language` |
 | `gitbook` | [SemVer](http://semver.org) condition to validate which GitBook version should be used |
-| `plugins` | List of plugins to load, See [the plugins section](#plugins) for more details |
-| `pluginsConfig` |Configuration for plugins, See [the plugins section](#plugins) for more details |
+| `plugins` | List of plugins to load, See [the plugins section](plugins.md) for more details |
+| `pluginsConfig` |Configuration for plugins, See [the plugins section](plugins.md) for more details |
 
 
 ### Plugins
 
-Plugins and their configurations are specified in the `book.json`.
+Plugins and their configurations are specified in the `book.json`. See [the plugins section](plugins.md) for more details.
 
diff --git a/docs/languages.md b/docs/languages.md
index 9acead0..9a866be 100644
--- a/docs/languages.md
+++ b/docs/languages.md
@@ -7,3 +7,9 @@ GitBook supports building books written in multiple languages. Each language sho
 * [French](fr/)
 * [Español](es/)
 ```
+
+### Configuration for each language
+
+When a language book (ex: `en`) has a `book.json`, its configuration will extend the main configuration.
+
+The only exception is plugins, plugins are specify globally relative to the book, and language specific plugins can not be specified.
diff --git a/docs/plugins.md b/docs/plugins.md
index 4d9e7b6..ff56b7b 100644
--- a/docs/plugins.md
+++ b/docs/plugins.md
@@ -9,7 +9,7 @@ Plugins can be easily searched on [plugins.gitbook.com](https://plugins.gitbook.
 
 ### How to install a plugin?
 
-Once you find a plugin that you want to install, you need to add it to your book.json:
+Once you find a plugin that you want to install, you need to add it to your `book.json`:
 
 ```
 {
@@ -17,6 +17,10 @@ Once you find a plugin that you want to install, you need to add it to your book
 }
 ```
 
-You can also specify a specific version using: "myPlugin@0.3.1". By default GitBook will resolve the latest version of the plugin compatbile with the current GitBook version.
+You can also specify a specific version using: `"myPlugin@0.3.1"`. By default GitBook will resolve the latest version of the plugin compatbile with the current GitBook version.
 
 Plugins are automatically installed on [GitBook.com](https://www.gitbook.com). Locally, run `gitbook install` to install and prepare all plugins for your books.
+
+### Configuring plugins
+
+PLugins specific configurations are stored in `pluginsConfig`. You have to refer to the documentation of the plugin itself for details about the available options.
diff --git a/docs/templating.md b/docs/templating.md
index c3ab084..38df38e 100644
--- a/docs/templating.md
+++ b/docs/templating.md
@@ -8,27 +8,83 @@ The Nunjucks syntax is very similar to **Jinja2** or **Liquid**.
 
 A variable looks up a value from the template context. If you wanted to simply display a variable, you would do:
 
-```
+```twig
 {{ username }}
 ```
 
 This looks up username from the context and displays it. Variable names can have dots in them which lookup properties, just like javascript. You can also use the square bracket syntax.
 
-```
+```twig
 {{ foo.bar }}
 {{ foo["bar"] }}
 ```
 
 If a value is undefined, nothing is displayed. The following all output nothing if foo is undefined: `{{ foo }}`, `{{ foo.bar }}`, `{{ foo.bar.baz }}`.
 
+GitBook provides a set of [context variables](variables.md).
+
 ### Filters
 
 Filters are essentially functions that can be applied to variables. They are called with a pipe operator (`|`) and can take arguments.
 
-```
+```twig
 {{ foo | title }}
 {{ foo | join(",") }}
 {{ foo | replace("foo", "bar") | capitalize }}
 ```
 
 The third example shows how you can chain filters. It would display "Bar", by first replacing "foo" with "bar" and then capitalizing it.
+
+### Tags
+
+##### if
+
+`if` tests a condition and lets you selectively display content. It behaves exactly as javascript's if behaves.
+
+```twig
+{% if variable %}
+  It is true
+{% endif %}
+```
+
+If variable is defined and evaluates to true, "It is true" will be displayed. Otherwise, nothing will be.
+
+You can specify alternate conditions with elif and else:
+
+```twig
+{% if hungry %}
+  I am hungry
+{% elif tired %}
+  I am tired
+{% else %}
+  I am good!
+{% endif %}
+```
+
+##### for
+
+`for` iterates over arrays and dictionaries.
+
+```twig
+# Chapters about GitBook
+
+{% for article in glossary.terms['gitbook'].articles %}
+* [{{ article.title }}]({{ article.path }})
+{% endfor %}
+```
+
+##### set
+
+`set` lets you create/modify a variable.
+
+```twig
+{% set softwareVersion = "1.0.0" %}
+
+Current version is {{ softwareVersion }}.
+[Download it](website.com/download/{{ softwareVersion }})
+```
+
+##### include and block
+
+Inclusion and inheritance is detailled in the [ConRefs](conrefs.md) section.
+