Bump version to 3.0.0-pre.3

.gitbook

@@ -1 +0,0 @@
-./docs

.gitignore

@@ -28,7 +28,7 @@ build/Release
 *.swp
 
 # Output of documentation
-docs/_book
+_book
 
 book.pdf
 book.epub

book.js

@@ -1,6 +1,7 @@
-var pkg = require('../package.json');
+var pkg = require('./package.json');
 
 module.exports = {
+    root: './docs',
     title: 'GitBook Documentation',
 
     plugins: ['theme-official'],

docs/SUMMARY.md

@@ -9,25 +9,25 @@
 
 * [Directory structure](structure.md)
 * [Pages and Summary](pages.md)
+* [Configuration](config.md)
 * [Glossary](lexicon.md)
 * [Multi-Lingual](languages.md)
-* [Configuration](config.md)
 * [AsciiDoc](asciidoc.md)
 
-### Miscellaneous
-
-* [Templating](templating.md)
-* [Content References](conrefs.md)
-* [Variables](variables.md)
-
 ### Customization
 
-* [Plugins](plugins.md)
-* [Theming](themes.md)
+* [Templating](templating/README.md)
+    * [Content References](templating/conrefs.md)
+    * [Variables](templating/variables.md)
+* [Plugins](plugins/README.md)
+    * [Create a plugin](plugins/create.md)
+    * [Test your plugin](plugins/testing.md)
+* [Theming](themes/README.md)
 
 --
 
 * [FAQ](faq.md)
+* [Examples](examples.md)
 * [Release notes](https://github.com/GitbookIO/gitbook/blob/master/CHANGES.md)
 
 

docs/asciidoc.md

@@ -54,7 +54,7 @@ This file is used to define terms. [See the glossary section](./lexicon.md).
 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.
+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").
 ```
 
 

docs/config.md

@@ -1,11 +1,12 @@
 # Configuration
 
-GitBook allows you to customize your book using a flexible configuration. These options are specified in a `book.json` file.
+GitBook allows you to customize your book using a flexible configuration. These options are specified in a `book.json` file. For authors, not used to write JSON, you can validate the syntax using [jsonlint](http://jsonlint.com).
 
 ### Configuration Settings
 
 | Variable | Description |
 | -------- | ----------- |
+| `root` | Path to the root folder containing the content |
 | `title` | Title of your book, default value is extracted from the README. On GitBook.com this field is pre-filled. |
 | `description` | Description of your book, default value is extracted from the README. On GitBook.com this field is pre-filled. |
 | `author` | Name of the author. On GitBook.com this field is pre-filled. |
@@ -13,8 +14,8 @@ 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.md) for more details |
-| `pluginsConfig` |Configuration for plugins, See [the plugins section](plugins.md) for more details |
+| `plugins` | List of plugins to load, See [the plugins section](plugins/README.md) for more details |
+| `pluginsConfig` |Configuration for plugins, See [the plugins section](plugins/README.md) for more details |
 
 ### PDF Options
 
@@ -33,5 +34,5 @@ PDF Output can be customized using a set of options in the `book.json`:
 
 ### Plugins
 
-Plugins and their configurations are specified in the `book.json`. See [the plugins section](plugins.md) for more details.
+Plugins and their configurations are specified in the `book.json`. See [the plugins section](plugins/README.md) for more details.
 

docs/languages.md

@@ -3,6 +3,8 @@
 GitBook supports building books written in multiple languages. Each language should be a sub-directory following the normal GitBook format, and a file named `LANGS.md` should be present at the root of the repository with the following format:
 
 ```markdown
+# Languages
+
 * [English](en/)
 * [French](fr/)
 * [Español](es/)

docs/plugins/README.md

@@ -19,6 +19,8 @@ Once you find a plugin that you want to install, you need to add it to your `boo
 
 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.
 
+### GitBook.com
+
 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

docs/plugins/create.md

@@ -0,0 +1,63 @@
+# Create and publish a plugin
+
+A GitBook plugin is a node package published on NPM that follow a defined convention.
+
+## Structure
+
+#### package.json
+
+The `package.json` is a manifest format for describing **Node.js modules**. GitBook plugins are built on top of Node modules. It declares dependencies, version, ownership, and other information required to run a plugin in GitBook. This document describes the schema in detail.
+
+```
+{
+    "name": "gitbook-plugin-mytest",
+    "version": "0.0.1",
+    "description": "This is my first GitBook plugin",
+    "engines": {
+        "gitbook": ">1.x.x"
+    }
+}
+```
+
+You can learn more about `package.json` from the [NPM documentation](https://docs.npmjs.com/files/package.json).
+
+The **package name** must begin with `gitbook-plugin-` and the **package engines** should contains `gitbook`.
+
+#### index.js
+
+The `index.js` is main entry point of your plugin runtime:
+
+```js
+module.exports = {
+    // Map of hooks
+    hooks: {},
+
+    // Map of new blocks
+    blocks: {},
+
+    // Map of new filters
+    filters: {}
+};
+```
+
+## Publish your plugin
+
+GitBook plugins can be published on [NPM](https://www.npmjs.com).
+
+To publish a new plugin, you need to create an account on [npmjs.com](https://www.npmjs.com) then publish it from the command line:
+
+```
+$ npm publish
+```
+
+## Private plugins
+
+Private plugins can be hosted on GitHub and included using `git` urls:
+
+```
+{
+    "plugins": [
+        "myplugin@git+https://github.com/MyCompany/mygitbookplugin.git#1.0.0"
+    ]
+}
+```

docs/plugins/testing.md

@@ -0,0 +1,22 @@
+# Testing your plugin
+
+### Testing your plugin locally
+
+Testing your plugin on your book before plushing it is possible using [npm link](https://docs.npmjs.com/cli/link).
+
+In the plugin's folder, run:
+
+```
+$ npm link
+```
+
+The nin your book's folder:
+
+```
+$ npm link gitbook-plugin-<plugin's name>
+```
+
+### Unit testing on Travis
+
+[gitbook-tester](https://github.com/todvora/gitbook-tester) makes it easy to write **Node.js/Mocha** unit tests for your plugins. Using [Travis.org](https://travis.org), tests can be run on each commits/tags.
+

docs/structure.md

@@ -1,6 +1,6 @@
 # Directory structure
 
-GitBook uses a very simple and obvious directory sttructure:
+GitBook uses a very simple and obvious directory structure:
 
 ```
 .
@@ -45,18 +45,20 @@ bin/*
 
 ### Project documentation / Sub-directory {#subdirectory}
 
-For project documentaiton, it sometimes better to use a diretcory (like `docs/`) to store the prject's documentation. You can use a `.gitbook` file to indicate to GitBook in which folder the book is stored:
+For software project, it sometimes better to use a diretcory (like `docs/`) to store the project's documentation. You can use the [`root` option](config.md) to indicate to GitBook in which folder the book is stored:
 
 ```
 .
-├── .gitbook
+├── book.json
 └── docs/
     ├── README.md
     └── SUMMARY.md
 ```
 
-With `.gitbook` containing:
+With `book.json` containing:
 
 ```
-./docs/
+{
+    "root": "./docs"
+}
 ```

lib/book.js

@@ -123,7 +123,16 @@ Book.prototype.getContext = function() {
 
 // Parse and prepare the configuration, fail if invalid
 Book.prototype.prepareConfig = function() {
-    return this.config.load();
+    var that = this;
+
+    return this.config.load()
+    .then(function() {
+        var rootFolder = that.config.get('root');
+        if (!rootFolder) return;
+
+        that.originalRoot = that.root;
+        that.root = path.resolve(that.root, rootFolder);
+    });
 };
 
 // Resolve a path in the book source
@@ -344,35 +353,14 @@ Book.prototype.isInLanguageBook = function(filename) {
     });
 };
 
-// Locate a book in a folder
-// - Read the ".gitbook" is exists
-// - Try the folder itself
-// - Try a "docs" folder
-Book.locate = function(fs, root) {
-    return fs.readAsString(path.join(root, '.gitbook'))
-    .then(function(content) {
-        return path.join(root, content);
-    }, function() {
-        // .gitbook doesn't exists, fall back to the root folder
-        return Promise(root);
-    });
-};
-
-// Locate and setup a book
-Book.setup = function(fs, root, opts) {
-    return Book.locate(fs, root)
-    .then(function(_root) {
-        return new Book(_.extend(opts || {}, {
-            root: _root,
-            fs: fs
-        }));
-    });
-};
-
 // Initialize a book
 Book.init = function(fs, root, opts) {
-    return Book.setup(fs, root, opts)
-    .then(initBook);
+    var book = new Book(_.extend(opts || {}, {
+        root: root,
+        fs: fs
+    }));
+
+    return initBook(book);
 };
 
 

lib/cli/helper.js

@@ -42,12 +42,13 @@ var FORMATS = {
 function bookCmd(fn) {
     return function(args, kwargs) {
         var input = path.resolve(args[0] || process.cwd());
-        return Book.setup(nodeFS, input, {
+        var book = new Book({
+            fs: nodeFS,
+            root: input,
             logLevel: kwargs.log
-        })
-        .then(function(book) {
-            return fn(book, args.slice(1), kwargs);
         });
+
+        return fn(book, args.slice(1), kwargs);
     };
 }
 

lib/cli/index.js

@@ -131,26 +131,27 @@ module.exports = {
 
                     // Generate the book
                     .then(function() {
-                        return Book.setup(helper.nodeFS, input, {
-                            'logLevel': kwargs.log
-                        })
-                        .then(function(book) {
-                            return book.parse()
-                            .then(function() {
-                                // Add livereload plugin
-                                book.config.set('plugins',
-                                    book.config.get('plugins')
-                                    .concat([
-                                        { name: 'livereload' }
-                                    ])
-                                );
+                        var book = new Book({
+                            fs: helper.nodeFS,
+                            root: input,
+                            logLevel: kwargs.log
+                        });
 
-                                var Out = helper.FORMATS[kwargs.format];
-                                var output = new Out(book);
+                        return book.parse()
+                        .then(function() {
+                            // Add livereload plugin
+                            book.config.set('plugins',
+                                book.config.get('plugins')
+                                .concat([
+                                    { name: 'livereload' }
+                                ])
+                            );
 
-                                return output.generate()
-                                .thenResolve(output);
-                            });
+                            var Out = helper.FORMATS[kwargs.format];
+                            var output = new Out(book);
+
+                            return output.generate()
+                            .thenResolve(output);
                         });
                     })
 

lib/config/schema.js

@@ -4,6 +4,10 @@ module.exports = {
     'title': 'GitBook Configuration',
     'type': 'object',
     'properties': {
+        'root': {
+            'type': 'string',
+            'title': 'Path fro the root folder containing the book\'s content'
+        },
         'title': {
             'type': 'string',
             'title': 'Title of the book, default is extracted from README'

lib/output/base.js

@@ -147,6 +147,7 @@ Output.prototype.prepare = function() {
         '.ignore',
         '.bookignore',
         'node_modules',
+        '_layouts',
 
         // The configuration file should not be copied in the output
         this.book.config.path,

lib/output/json.js

@@ -22,7 +22,7 @@ JSONOutput.prototype.onPage = function(page) {
         delete json.config;
 
         // Specify JSON output version
-        json.version = '2';
+        json.version = '3';
 
         return that.writeFile(
             page.withExtension('.json'),

package.json

@@ -1,6 +1,6 @@
 {
     "name": "gitbook",
-    "version": "3.0.0-pre.2",
+    "version": "3.0.0-pre.3",
     "homepage": "https://www.gitbook.com",
     "description": "Library and cmd utility to generate GitBooks",
     "main": "lib/index.js",

test/config.js

@@ -46,7 +46,7 @@ describe('Configuration', function() {
             return mock.setupDefaultBook()
             .then(function(_book) {
                 book = _book;
-                return book.config.load();
+                return book.prepareConfig();
             });
         });
 
@@ -64,7 +64,7 @@ describe('Configuration', function() {
             })
             .then(function(_book) {
                 book = _book;
-                return book.config.load();
+                return book.prepareConfig();
             });
         });
 
@@ -82,7 +82,7 @@ describe('Configuration', function() {
             })
             .then(function(_book) {
                 book = _book;
-                return book.config.load();
+                return book.prepareConfig();
             });
         });
 

test/glossary.js

@@ -7,7 +7,7 @@ describe('Glossary', function() {
             'GLOSSARY.md': ''
         })
         .then(function(book) {
-            return book.config.load()
+            return book.prepareConfig()
 
             .then(function() {
                 return book.glossary.load();
@@ -27,7 +27,7 @@ describe('Glossary', function() {
             })
             .then(function(_book) {
                 book = _book;
-                return book.config.load();
+                return book.prepareConfig();
             })
             .then(function() {
                 return book.glossary.load();

test/langs.js

@@ -6,7 +6,7 @@ describe('Langs', function() {
             'LANGS.md': ''
         })
         .then(function(book) {
-            return book.config.load()
+            return book.prepareConfig()
 
             .then(function() {
                 return book.langs.load();

test/locate.js

@@ -1,27 +1,34 @@
 var path = require('path');
+var should = require('should');
 
 var Book = require('../').Book;
 var mock = require('./mock');
 
 describe('Locate', function() {
     it('should use root folder if no .gitbook', function() {
-        return mock.setupFS({
+        return mock.setupBook({
             'README.md': '# Hello'
         })
-        .then(function(root) {
-            return Book.locate(mock.fs, root)
-                .should.be.fulfilledWith(root);
+        .then(function(book) {
+            return book.prepareConfig()
+            .then(function() {
+                should(book.originalRoot).not.be.ok();
+            });
         });
     });
 
-    it('should use resolve using .gitbook', function() {
-        return mock.setupFS({
+    it('should use resolve using book.js root property', function() {
+        return mock.setupBook({
             'README.md': '# Hello',
-            '.gitbook': './docs'
+            'docs/README.md': '# Hello Book',
+            'book.json': { root: './docs' }
         })
-        .then(function(root) {
-            return Book.locate(mock.fs, root)
-                .should.be.fulfilledWith(path.resolve(root, 'docs'));
+        .then(function(book) {
+            return book.prepareConfig()
+            .then(function() {
+                should(book.originalRoot).be.ok();
+                book.root.should.equal(path.resolve(book.originalRoot, 'docs'));
+            });
         });
     });
 

test/plugins.js

@@ -53,7 +53,23 @@ describe('Plugins', function() {
                 }
             })
             .then(function(book) {
-                return book.config.load()
+                return book.prepareConfig()
+                .then(function() {
+                    var plugins = new PluginsManager(book);
+                    return plugins.install();
+                });
+            })
+            .should.be.fulfilledWith(1);
+        });
+
+        it('should correctly install dependencies from GitHub', function() {
+            return mock.setupBook({
+                'book.json': {
+                    plugins: ['ga@git+https://github.com/GitbookIO/plugin-ga#master']
+                }
+            })
+            .then(function(book) {
+                return book.prepareConfig()
                 .then(function() {
                     var plugins = new PluginsManager(book);
                     return plugins.install();
@@ -90,7 +106,7 @@ describe('Plugins', function() {
                 }
             })
             .then(function(book2) {
-                return book2.config.load()
+                return book2.prepareConfig()
                 .then(function() {
                     var plugin = new BookPlugin(book2, 'test-config');
                     return plugin.load(PLUGINS_ROOT);

test/readme.js

@@ -6,7 +6,7 @@ describe('Readme', function() {
             'README.md': ''
         })
         .then(function(book) {
-            return book.config.load()
+            return book.prepareConfig()
 
             .then(function() {
                 return book.readme.load();