End of review

10 files changed, 40 insertions, 28 deletions

diff --git a/docs/README.md b/docs/README.md
index 12b0e6c..2e8f7d9 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,7 +4,7 @@
 
 GitBook is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown (or AsciiDoc). Here is an example: [Learn Javascript](https://www.gitbook.com/book/GitBookIO/javascript). This documentation has been generated using GitBook.
 
-GitBook can output your content as a website ([customizable](themes/README.md) and [extensibles](plugins/README.md)) or as an ebook (PDF, ePub or Mobi).
+GitBook can output your content as a website ([customizable](/themes/) and [extensibles](/plugins/)) or as an ebook (PDF, ePub or Mobi).
 
 [GitBook.com](https://www.gitbook.com) is the online platform to create and host books built using the GitBook format. It offers hosting, collaboration features and an [easy-to-use editor](https://www.gitbook.com/editor).
 
diff --git a/docs/asciidoc.md b/docs/asciidoc.md
index 0dfbb41..d51ebcc 100644
--- a/docs/asciidoc.md
+++ b/docs/asciidoc.md
@@ -51,10 +51,15 @@ This file is used to define terms. [See the glossary section](./lexicon.md).
 = Glossary
 
 == Magic
-Sufficiently advanced technology, beyond the understanding of the observer producing a sense of wonder.
+
+Sufficiently advanced technology, beyond the understanding of the
+observer producing a sense of wonder.
 
 == PHP
-A popular web programming language, used by many large websites such as Facebook. Rasmus Lerdorf originally created PHP in 1994 to power his personal homepage (PHP originally stood for "Personal Home Page" but now stands for "PHP: Hypertext Preprocessor").
-```
+
+A popular web programming language, used by many large websites such
+as Facebook. Rasmus Lerdorf originally created PHP in 1994 to power
+his personal homepage (PHP originally stood for "Personal Home Page"
+but now stands for "PHP: Hypertext Preprocessor"). ```
 
 
diff --git a/docs/config.md b/docs/config.md
index fc9b411..2f2fd85 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -17,13 +17,21 @@ GitBook allows you to customize your book using a flexible configuration. These
 
 ### Plugins
 
-Plugins and their configurations are specified in the `book.json`. See [the plugins section](plugins/README.md) for more details.
+Plugins and their configurations are specified in the `book.json`. See [the plugins section](/plugins/) for more details.
 
 | Variable | Description |
 | -------- | ----------- |
 | `plugins` | List of plugins to load |
 | `pluginsConfig` |Configuration for plugins |
 
+### Theme
+
+Since version 3.0.0, GitBook can use themes. See [the theming section](/themes/) for more details.
+
+| Variable | Description |
+| -------- | ----------- |
+| `theme` | The theme to use for the book |
+
 ### PDF Options
 
 PDF Output can be customized using a set of options in the `book.json`:
diff --git a/docs/examples.md b/docs/examples.md
index 2dbaea8..fc1cfe6 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -17,11 +17,11 @@ More than 50,000 books have benn published on [GitBook.com](https://www.gitbook.
 
 ### Research Papers
 
-- [TowCenter Collection](https://www.gitbook.com/@towcenter) by [Columbia Journalism School]()
+- [TowCenter Collection](https://www.gitbook.com/@towcenter) by [Columbia Journalism School](http://www.journalism.columbia.edu/)
 - [Block Relaxation Algorithms in Statistics](https://www.gitbook.com/@jandeleeuw) by Jan de Leeuw
 
 ### Documentation
 
-- [DuckDuckHack Documentation](http://docs.duckduckhack.com) by DuckDuckGo
+- [DuckDuckHack Documentation](http://docs.duckduckhack.com) by [DuckDuckGo](https://duckduckgo.com/about)
 - This documentation
 
diff --git a/docs/faq.md b/docs/faq.md
index ff3628e..b7a8b8b 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -26,8 +26,8 @@ GitBook supports math equations and TeX thanks to plugins. There are currently 2
 
 #### Can I customize/theme the output?
 
-Yes, both the website and ebook outputs can be customized using [themes](themes/README.md).
+Yes, both the website and ebook outputs can be customized using [themes](/themes/).
 
 #### Can I add interactive content (videos, etc)?
 
-GitBook is very [extensible](plugins.md). You can use [existing plugins](https://plugins.gitbook.com) or create your own!
+GitBook is very [extensible](/plugins/). You can use [existing plugins](https://plugins.gitbook.com) or create your own!
diff --git a/docs/plugins/README.md b/docs/plugins/README.md
index eeed839..4df62b8 100644
--- a/docs/plugins/README.md
+++ b/docs/plugins/README.md
@@ -25,4 +25,4 @@ Plugins are automatically installed on [GitBook.com](https://www.gitbook.com). L
 
 ### 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.
+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/README.md b/docs/templating/README.md
index 38df38e..963f921 100644
--- a/docs/templating/README.md
+++ b/docs/templating/README.md
@@ -1,18 +1,18 @@
 # Templating
 
-GitBook uses the Nunjucks templating language to process pages and theme's templates.
+GitBook uses the [Nunjucks templating language](https://mozilla.github.io/nunjucks/) to process pages and theme's templates.
 
-The Nunjucks syntax is very similar to **Jinja2** or **Liquid**.
+The Nunjucks syntax is very similar to **Jinja2** or **Liquid**. Its syntax uses surrounding braces `{ }` to mark content that needs to be processed.
 
 ### Variables
 
-A variable looks up a value from the template context. If you wanted to simply display a variable, you would do:
+A variable looks up a value from the template context. If you wanted to simply display a variable, you would use the `{{ variable }}` syntax. For example :
 
 ```twig
-{{ username }}
+My name is {{ name }}, nice to meet you
 ```
 
-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.
+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 }}
@@ -21,7 +21,7 @@ This looks up username from the context and displays it. Variable names can have
 
 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).
+GitBook provides a set of [predefined  variables](variables.md) from the context.
 
 ### Filters
 
@@ -39,7 +39,7 @@ The third example shows how you can chain filters. It would display "Bar", by fi
 
 ##### if
 
-`if` tests a condition and lets you selectively display content. It behaves exactly as javascript's if behaves.
+`if` tests a condition and lets you selectively display content. It behaves exactly as JavaScript's `if` behaves.
 
 ```twig
 {% if variable %}
@@ -49,7 +49,7 @@ The third example shows how you can chain filters. It would display "Bar", by fi
 
 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:
+You can specify alternate conditions with `elif` and `else`:
 
 ```twig
 {% if hungry %}
@@ -86,5 +86,4 @@ Current version is {{ softwareVersion }}.
 
 ##### include and block
 
-Inclusion and inheritance is detailled in the [ConRefs](conrefs.md) section.
-
+Inclusion and inheritance is detailled in the [Content References](conrefs.md) section.
diff --git a/docs/templating/conrefs.md b/docs/templating/conrefs.md
index 4eb6e0b..252fec9 100644
--- a/docs/templating/conrefs.md
+++ b/docs/templating/conrefs.md
@@ -1,10 +1,10 @@
 # Content References
 
-Content referencing (conref) is a convenient mechanism for reuse of content from other files or books.
+Content referencing (conref) is a convenient mechanism to reuse content from other files or books.
 
 ### Importing local files
 
-Importing an other file's content is really easy using the `include` tag:
+Importing an other file's content is easy using the `include` tag:
 
 ```
 {% include "./test.md" %}
@@ -42,7 +42,7 @@ Template inheritance is a way to make it easy to reuse templates. When writing a
 {% endblock %}
 ```
 
-In the file `mypage.md`, you should specify the blocks that can be extent:
+In the file `mypage.md`, you should specify the blocks that can be extended:
 
 ```
 {% block pageContent %}
diff --git a/docs/templating/variables.md b/docs/templating/variables.md
index 3dbd6f7..bca5880 100644
--- a/docs/templating/variables.md
+++ b/docs/templating/variables.md
@@ -6,7 +6,7 @@ The following is a reference of the available data during book's parsing and the
 
 | Variable | Description |
 | -------- | ----------- |
-| `book` | Bookwide information + configuration settings from `book.json`. See below for details. |
+| `book` | Book-wide information + configuration settings from `book.json`. See below for details. |
 | `gitbook` | GitBook specific information |
 | `page` | Current page specific information |
 | `file` | File associated with the current page specific information |
@@ -25,7 +25,7 @@ The following is a reference of the available data during book's parsing and the
 
 | Variable | Description |
 | -------- | ----------- |
-| `gitbook.time` | The current time (when you run the `gitbook` command). |
+| `gitbook.time` | The current time (when you run the `gitbook` command) . |
 | `gitbook.version` | Version of GitBook used to generate the book |
 
 ### File Variables
@@ -33,7 +33,7 @@ The following is a reference of the available data during book's parsing and the
 | Variable | Description |
 | -------- | ----------- |
 | `file.path` | The path to the raw page |
-| `file.mtime` | Modified Time, Time when file data last modified |
+| `file.mtime` | Modified Time. Last time the file was modified |
 | `file.type` | The name of the parser used to compile this file (ex: `markdown`, `asciidoc`, etc) |
 
 #### Page Variables
@@ -51,7 +51,7 @@ The following is a reference of the available data during book's parsing and the
 | -------- | ----------- |
 | `summary.parts` | List of sections in the Table of Contents |
 
-Thw whole table of contents (`SUMMARY.md`) can be accessed:
+The whole table of contents (`SUMMARY.md`) can be accessed:
 
 `summary.parts[0].articles[0].title` will return the title of the first article.
 
diff --git a/docs/themes/README.md b/docs/themes/README.md
index 48c19db..bacde12 100644
--- a/docs/themes/README.md
+++ b/docs/themes/README.md
@@ -23,4 +23,4 @@ Authors can extend the templates of a theme directly from the book source (witho
 
 ### Publish a theme
 
-Themes are published as plugins ([see related docs](plugins.md)) with a `theme-` prefix. For example the theme `awesome` will be loaded from `theme-awesome` plugin, and then from `gitbook-plugin-theme-awesome` NPM package.
+Themes are published as plugins ([see related docs](/plugins/)) with a `theme-` prefix. For example the theme `awesome` will be loaded from the `theme-awesome` plugin, and then from the `gitbook-plugin-theme-awesome` NPM package.