Reviewing, first part

1 files changed, 37 insertions, 7 deletions

diff --git a/docs/pages.md b/docs/pages.md
index 8ffa054..46799b3 100644
--- a/docs/pages.md
+++ b/docs/pages.md
@@ -1,12 +1,12 @@
 # Pages and Summary
 
-GitBook uses a `SUMMARY.md` file to define the structure of chapters and subchapters of the book. The `SUMMARY.md` file is used to generate the book's table of contents.
-
 ### Summary
 
-The `SUMMARY.md`'s format is simply a list of links, the title of the link is used as the chapter's title, and the target is a path to that chapter's file.
+GitBook uses a `SUMMARY.md` file to define the structure of chapters and subchapters of the book. The `SUMMARY.md` file is used to generate the book's table of contents.
 
-Subchapters are defined simply by adding a nested list to a parent chapter.
+The format of `SUMMARY.md` is just a list of links. The link's title is used as the chapter's title, and the link's target is a path to that chapter's file.
+
+Adding a nested list to a parent chapter will create subchapters.
 
 ##### Simple example
 
@@ -21,23 +21,50 @@ Subchapters are defined simply by adding a nested list to a parent chapter.
     * [Better tools for authors](part2/better_tools.md)
 ```
 
+Each chapter has a dedicated page (`part#/README.md`) and is split into subchapters.
+
 ##### Example with subchapters split into parts
 
 ```markdown
 # Summary
 
-### Part 1
+### Part I
 
 * [Writing is nice](part1/writing.md)
 * [GitBook is nice](part1/gitbook.md)
 
-### Part 2
+### Part II
 
 * [We love feedback](part2/feedback_please.md)
 * [Better tools for authors](part2/better_tools.md)
 ```
 
-### Front Matter
+Here, parts are just groups of chapters and do not have dedicated pages, but will show in the navigation for example.
+
+### Pages
+
+#### Markdown syntax
+
+Most of the files for GitBook use the Markdown syntax by default. GitBook infers your pages's structure from it. The syntax used is similar to the [GitHub Flavored Markdown syntax](https://guides.github.com/features/mastering-markdown/). One can also opt for the [AsciiDoc syntax](asciidoc.md).
+
+##### Example of a chapter file
+
+``` markdown
+# Title of the chapter
+
+This is a great introduction.
+
+## Section 1
+
+Markdown will dictates _most_ of your **book's structure**
+
+## Section 2
+
+...
+
+```
+
+#### Front Matter
 
 Pages can contain an optional front matter. It can be used to define the page's description. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:
 
@@ -47,4 +74,7 @@ description: This is a short description of my page
 ---
 
 # The content of my page
+...
 ```
+
+The front matter can define variables of your own, they will be added to the [book variable](templating/variables.md) so you can use them in your templating.