Improve documentation

4 files changed, 88 insertions, 1 deletions

diff --git a/docs/README.md b/docs/README.md
index 8329a5c..6febb43 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,6 +1,22 @@
-# GitBook Documentation: v{{ book.version }}
+# GitBook Format Documentation
+
+> This documentation is for GitBook version **{{ book.version }}**
+
+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.md) and [extensibles](plugins.md)) 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).
+
+### Help and Support
+
+We're always happy to help out with your books or any other questions you might have. You can ask a question on the following contact form at [gitbook.com/contact](https://www.gitbook.com/contact) or signal an issue on [GitHub](https://github.com/GitbookIO/gitbook).
 
 ### FAQ
 
 There are questions that are asked quite often, [check this out before creating an issue](faq.md).
 
+### Contribute to this documentation
+
+You can contribute to improve this documentation on [GitHub](https://github.com/GitbookIO/gitbook) by signaling issues or proposing changes.
+
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 71f9e68..a304801 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -12,6 +12,7 @@
 * [Glossary](lexicon.md)
 * [Multi-Lingual](languages.md)
 * [Configuration](config.md)
+* [AsciiDoc](asciidoc.md)
 
 ### Miscellaneous
 
@@ -28,3 +29,5 @@
 
 * [FAQ](faq.md)
 * [Release notes](https://github.com/GitbookIO/gitbook/blob/master/CHANGES.md)
+
+
diff --git a/docs/asciidoc.md b/docs/asciidoc.md
new file mode 100644
index 0000000..6fe0dec
--- /dev/null
+++ b/docs/asciidoc.md
@@ -0,0 +1,60 @@
+# AsciiDoc
+
+Since version `2.0.0`, GitBook can also accept AsciiDoc as an input format.
+
+Please refer to the [AsciiDoc Syntax Quick Reference](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) for more informations about the format.
+
+Just like for markdown, GitBook is using some special files to extract structures: `README.adoc`, `SUMMARY.adoc`, `LANGS.adoc` and `GLOSSARY.adoc`.
+
+### README.adoc
+
+This is the main entry of your book: the introduction. This file is **non optional**.
+
+### SUMMARY.adoc
+
+This file defines the list of chapters and subchapters. Just like [for markdown](./pages.md), the `SUMMARY.adoc`'s format is simply a list of links, the name of the link is used as the chapter's name, and the target is a path to that chapter's file.
+
+Subchapters are defined simply by adding a nested list to a parent chapter.
+
+```asciidoc
+= Summary
+
+. link:chapter-1/README.adoc[Chapter 1]
+.. link:chapter-1/ARTICLE1.adoc[Article 1]
+.. link:chapter-1/ARTICLE2.adoc[Article 2]
+... link:chapter-1/ARTICLE-1-2-1.adoc[Article 1.2.1]
+. link:chapter-2/README.adoc[Chapter 2]
+. link:chapter-3/README.adoc[Chapter 3]
+. link:chapter-4/README.adoc[Chapter 4]
+.. Unfinished article
+. Unfinished Chapter
+```
+
+### LANGS.adoc
+
+For [Multi-Languages](./languages.md) books, this file is used to define the different supported languages and translations.
+
+This file is following the same syntax as the `SUMMARY.adoc`:
+
+```asciidoc
+= Languages
+
+. link:en/[English]
+. link:fr/[French]
+```
+
+### GLOSSARY.adoc
+
+This file is used to define terms. [See the glossary section](./lexicon.md).
+
+```asciidoc
+= Glossary
+
+== Magic
+Sufficiently advanced technology, beyond the understanding of the observer producing a sense of wonder.
+
+== PHP
+An atrocious language, invented for the sole purpose of inflicting pain and suffering amongst the programming wizards of this world.
+```
+
+
diff --git a/docs/setup.md b/docs/setup.md
index aaa0407..3ce416e 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -35,3 +35,11 @@ $ npm install gitbook-cli -g
 $ gitbook install beta
 ```
 
+##### Debugging
+
+You can use the options `--log=debug` and `--debug` to get better error messages (with stack trace). For example:
+
+```
+$ gitbook build ./ --log=debug --debug
+```
+