Bump version to 3.2.0-pre.0

add open and browser args to serve command

CHANGES.md

@@ -2,7 +2,36 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
-## 3.0.0 (pre)
+## 3.2.0 (pre)
+- Switch markdown parser from `kramed` to `markup-it`
+- Fix support of `|` in tables
+
+## 3.1.1
+- Fix order of plugins during loading
+- Fix error when using math and conrefs
+- Fix target attribute for external links
+- Fix serve command
+
+## 3.1.0
+- Always load themes after plugins
+- README/Introduction doesn't require to be the first entry in the summary
+- Highlight active entry in summary when scrolling a page with anchors
+- Support empty parts in summary
+
+## 3.0.3
+- Fix redirection in `gitbook serve` when accessing a folder without trailing slash
+- Fix links/annotations for glossary not being correctly resolved
+- Fix regression for supporting uppercase filenames in structure files
+- Fix `gitbook install` when using Git URLs for plugins
+
+## 3.0.2
+- Fix crash for anchor links
+
+## 3.0.1
+- Fix regression in link resolution when contain anchor
+- Fix `structure.<name>` configuration not supporting filenames with dots
+
+## 3.0.0
 - Summary can contain external links and anchors (Fix [#776](https://github.com/GitbookIO/gitbook/issues/776))
 - Summary can contain differents entitled sections
 - Glossary is generated as a normal page

appveyor.yml

@@ -5,13 +5,18 @@ init:
 # Test against these versions of Node.js.
 environment:
   matrix:
+    - nodejs_version: "6"
     - nodejs_version: "5"
     - nodejs_version: "4"
 
+matrix:
+  fast_finish: true
+
 # Install scripts. (runs after repo cloning)
 install:
   # Get the latest stable version of Node.js or io.js
   - ps: Install-Product node $env:nodejs_version
+  - set CI=true
   # install svgexport
   - npm install svgexport -g
   # install modules
@@ -27,3 +32,7 @@ test_script:
 
 # Don't actually build.
 build: off
+
+# Clone only last commit
+shallow_clone: true
+clone_depth: 1

docs/config.md

@@ -7,6 +7,7 @@ GitBook allows you to customize your book using a flexible configuration. These
 | Variable | Description |
 | -------- | ----------- |
 | `root` | Path to the root folder containing all the book's files, except `book.json`|
+| `structure` | To specify paths for Readme, Summary, Glossary etc. See [Structure paragraph](#structure). |
 | `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. |
@@ -19,18 +20,24 @@ GitBook allows you to customize your book using a flexible configuration. These
 
 Plugins and their configurations are specified in the `book.json`. See [the plugins section](plugins/README.md) for more details.
 
+Since version 3.0.0, GitBook can use themes. See [the theming section](themes/README.md) for more details.
+
 | Variable | Description |
 | -------- | ----------- |
 | `plugins` | List of plugins to load |
 | `pluginsConfig` |Configuration for plugins |
 
-### Theme
+### Structure
 
-Since version 3.0.0, GitBook can use themes. See [the theming section](themes/README.md) for more details.
+In addition to the `root` variable, you can tell Gitbook the name of the files for Readme, Summary, Glossary, Languages (instead of using the default names such as `README.md`).
+These files must be at the root of your book (or the root of every language book). Paths such as `dir/MY_README.md` are not accepted.
 
 | Variable | Description |
 | -------- | ----------- |
-| `theme` | The theme to use for the book |
+| `structure.readme` | Readme file name (defaults to `README.md`) |
+| `structure.summary` | Summary file name (defaults to `SUMMARY.md`) |
+| `structure.glossary` | Glossary file name (defaults to `GLOSSARY.md`) |
+| `structure.languages` | Languages file name (defaults to `LANGS.md`) |
 
 ### PDF Options
 

docs/ebook.md

@@ -29,12 +29,13 @@ You can replace `/usr/bin` with any directory that is in your $PATH.
 
 ### Cover
 
-Covers are used for all the ebook formats. It's an important part of an ebook brandline.
+Covers are used for all the ebook formats. You can either provide one yourself, or generate one using the [autocover plugin](https://plugins.gitbook.com/plugin/autocover).
+
+To provide a cover, place a **`cover.jpg`** file at the root directory of your book. Adding a **`cover_small.jpg`** will specify a smaller version of the cover. The cover should be a **JPEG** file.
 
 A good cover should respect the following guidelines:
 
-* Size of 1800x2360 (pixels)
+* Size of 1800x2360 pixels for `cover.jpg`, 200x262 for `cover_small.jpg`
 * No border
 * Clearly visible book title
 * Any important text should be visible in the small version
-

docs/plugins/api.md

@@ -37,7 +37,7 @@ var filepath = output.resolve('myimage.png');
 var fileurl = output.toURL('mychapter/README.md');
 
 // Write a file in the output folder
-output.write('hello.txt', 'Hello World')
+output.writeFile('hello.txt', 'Hello World')
     .then(function() { ... });
 
 // Copy a file to the output folder

docs/setup.md

@@ -14,7 +14,7 @@ It integrates well with the [GitBook Editor](https://www.gitbook.com/editor).
 
 Installing GitBook is easy and straightforward. Your system just needs to meet these two requirements:
 
-* NodeJS (v4.0.0 and above are adviced)
+* NodeJS (v4.0.0 and above is recommended)
 * Windows, Linux, Unix, or Mac OS X
 
 ##### Install with NPM

docs/templating/conrefs.md

@@ -51,5 +51,5 @@ This is the default content
 
 # License
 
-{% import "./LICENSE" %}
+{% include "./LICENSE" %}
 ```

docs/themes/README.md

@@ -17,7 +17,22 @@ A theme is a plugin containing templates and assets. Overriding any individual t
 
 ### Extend/Customize theme in a book
 
-Authors can extend the templates of a theme directly from their book's source (without creating an external theme). Templates will be resolved in the `_layouts` folder of the book first, then in
+Authors can extend the templates of a theme directly from their book's source (without creating an external theme). Templates will be resolved in the `_layouts` folder of the book first, then in the installed plugins/themes.
+
+### Extend instead of Forking
+
+When you want to make your theme changes available to multiple books, instead of forking the default theme, you can extend it using the [templating syntax](../templating/README.md):
+
+```html
+{% extends template.self %}
+
+{% block body %}
+    {{ super() }}
+    ... This will be added to the "body" block
+{% endblock %}
+```
+
+Take a look at the [API](https://github.com/GitbookIO/theme-api) theme for a more complete example.
 
 ### Publish a theme
 

lib/api/encodeGlobal.js

@@ -8,6 +8,7 @@ var deprecate = require('./deprecate');
 var fileToURL = require('../output/helper/fileToURL');
 var defaultBlocks = require('../constants/defaultBlocks');
 var gitbook = require('../gitbook');
+var parsers = require('../parsers');
 
 var encodeConfig = require('./encodeConfig');
 var encodeSummary = require('./encodeSummary');
@@ -95,6 +96,34 @@ function encodeGlobal(output) {
             return encodePage(output, page);
         },
 
+        /**
+            Render a block of text (markdown/asciidoc)
+
+            @param {String} type
+            @param {String} text
+            @return {Promise<String>}
+        */
+        renderBlock: function(type, text) {
+            var parser = parsers.get(type);
+
+            return parser.parsePage(text)
+                .get('content');
+        },
+
+        /**
+            Render an inline text (markdown/asciidoc)
+
+            @param {String} type
+            @param {String} text
+            @return {Promise<String>}
+        */
+        renderInline: function(type, text) {
+            var parser = parsers.get(type);
+
+            return parser.parseInline(text)
+                .get('content');
+        },
+
         template: {
             /**
                 Apply a templating block and returns its result
@@ -142,6 +171,21 @@ function encodeGlobal(output) {
                 return fileToURL(output, filePath);
             },
 
+            /**
+                Check that a file exists.
+
+                @param {String} fileName
+                @return {Promise}
+            */
+            hasFile: function(fileName, content) {
+                return Promise()
+                .then(function() {
+                    var filePath = PathUtils.resolveInRoot(outputFolder, fileName);
+
+                    return fs.exists(filePath);
+                });
+            },
+
             /**
                 Write a file to the output folder,
                 It creates the required folder
@@ -160,6 +204,27 @@ function encodeGlobal(output) {
                         return fs.writeFile(filePath, content);
                     });
                 });
+            },
+
+            /**
+                Copy a file to the output folder
+                It creates the required folder.
+
+                @param {String} inputFile
+                @param {String} outputFile
+                @param {Buffer} content
+                @return {Promise}
+            */
+            copyFile: function(inputFile, outputFile, content) {
+                return Promise()
+                .then(function() {
+                    var outputFilePath = PathUtils.resolveInRoot(outputFolder, outputFile);
+
+                    return fs.ensureFile(outputFilePath)
+                    .then(function() {
+                        return fs.copy(inputFile, outputFilePath);
+                    });
+                });
             }
         },
 

lib/browser.js

@@ -8,8 +8,18 @@ module.exports = {
     FS:                 require('./models/fs'),
     Summary:            require('./models/summary'),
     Glossary:           require('./models/glossary'),
+    Config:             require('./models/config'),
+    Page:               require('./models/page'),
+    PluginDependency:   require('./models/pluginDependency'),
 
     // Modifiers
-    SummaryModifier: Modifiers.Summary,
-    ConfigModifier: Modifiers.Config
+    SummaryModifier:    Modifiers.Summary,
+    ConfigModifier:     Modifiers.Config,
+
+    // Constants
+    CONFIG_FILES:        require('./constants/configFiles.js'),
+    IGNORE_FILES:        require('./constants/ignoreFiles.js'),
+    DEFAULT_PLUGINS:     require('./constants/defaultPlugins'),
+    EXTENSIONS_MARKDOWN: require('./constants/extsMarkdown'),
+    EXTENSIONS_ASCIIDOC: require('./constants/extsAsciidoc')
 };

lib/cli/serve.js

@@ -1,6 +1,7 @@
 /* eslint-disable no-console */
 
 var tinylr = require('tiny-lr');
+var open = require('open');
 
 var Parse = require('../parse');
 var Output = require('../output');
@@ -32,9 +33,11 @@ function generateBook(args, kwargs) {
     var outputFolder = getOutputFolder(args);
     var book = getBook(args, kwargs);
     var Generator = Output.getGenerator(kwargs.format);
+    var browser = kwargs['browser'];
 
     var hasWatch = kwargs['watch'];
     var hasLiveReloading = kwargs['live'];
+    var hasOpen = kwargs['open'];
 
     // Stop server if running
     if (server.isRunning()) console.log('Stopping server');
@@ -45,7 +48,9 @@ function generateBook(args, kwargs) {
         .then(function(resultBook) {
             if (hasLiveReloading) {
                 // Enable livereload plugin
-                resultBook = ConfigModifier.addPlugin(resultBook, 'livereload');
+                var config = resultBook.getConfig();
+                config = ConfigModifier.addPlugin(config, 'livereload');
+                resultBook = resultBook.set('config', config);
             }
 
             return Output.generate(Generator, resultBook, {
@@ -69,6 +74,10 @@ function generateBook(args, kwargs) {
                 }
             });
         }
+
+        if (hasOpen) {
+            open('http://localhost:'+port, browser);
+        }
     })
     .then(function() {
         if (!hasWatch) {
@@ -110,6 +119,16 @@ module.exports = {
             description: 'Enable live reloading',
             defaults: true
         },
+        {
+            name: 'open',
+            description: 'Enable opening book in browser',
+            defaults: false
+        },
+        {
+            name: 'browser',
+            description: 'Specify browser for opening book',
+            defaults: ''
+        },
         options.log,
         options.format
     ],

lib/cli/server.js

@@ -71,11 +71,18 @@ Server.prototype.start = function(dir, port) {
 
             // Redirect to directory's index.html
             function redirect() {
+                var resultURL = urlTransform(req.url, function(parsed) {
+                    parsed.pathname += '/';
+                    return parsed;
+                });
+
                 res.statusCode = 301;
-                res.setHeader('Location', req.url + '/');
-                res.end('Redirecting to ' + req.url + '/');
+                res.setHeader('Location', resultURL);
+                res.end('Redirecting to ' + resultURL);
             }
 
+            res.setHeader('X-Current-Location', req.url);
+
             // Send file
             send(req, url.parse(req.url).pathname, {
                 root: dir
@@ -106,4 +113,16 @@ Server.prototype.start = function(dir, port) {
     });
 };
 
+/**
+    urlTransform is a helper function that allows a function to transform
+    a url string in it's parsed form and returns the new url as a string
+
+    @param {String} uri
+    @param {Function} fn
+    @return {String}
+*/
+function urlTransform(uri, fn) {
+    return url.format(fn(url.parse(uri)));
+}
+
 module.exports = Server;

lib/constants/__tests__/configSchema.js

@@ -0,0 +1,46 @@
+var jsonschema = require('jsonschema');
+var schema = require('../configSchema');
+
+describe('configSchema', function() {
+
+    function validate(cfg) {
+        var v = new jsonschema.Validator();
+        return v.validate(cfg, schema, {
+            propertyName: 'config'
+        });
+    }
+
+    describe('structure', function() {
+
+        it('should accept dot in filename', function() {
+            var result = validate({
+                structure: {
+                    readme: 'book-intro.adoc'
+                }
+            });
+
+            expect(result.errors.length).toBe(0);
+        });
+
+        it('should accept uppercase in filename', function() {
+            var result = validate({
+                structure: {
+                    readme: 'BOOK.adoc'
+                }
+            });
+
+            expect(result.errors.length).toBe(0);
+        });
+
+        it('should not accept filepath', function() {
+            var result = validate({
+                structure: {
+                    readme: 'folder/myFile.md'
+                }
+            });
+
+            expect(result.errors.length).toBe(1);
+        });
+
+    });
+});

lib/constants/configSchema.js

@@ -1,3 +1,5 @@
+var FILENAME_REGEX = '^[a-zA-Z-._\d,\s]+$';
+
 module.exports = {
     '$schema': 'http://json-schema.org/schema#',
     'id': 'https://gitbook.com/schemas/book.json',
@@ -57,25 +59,25 @@ module.exports = {
                     'default': 'LANGS.md',
                     'type': 'string',
                     'title': 'File to use as languages index',
-                    'pattern': '^[0-9a-zA-Z ... ]+$'
+                    'pattern': FILENAME_REGEX
                 },
                 'readme': {
                     'default': 'README.md',
                     'type': 'string',
                     'title': 'File to use as preface',
-                    'pattern': '^[0-9a-zA-Z ... ]+$'
+                    'pattern': FILENAME_REGEX
                 },
                 'glossary': {
                     'default': 'GLOSSARY.md',
                     'type': 'string',
                     'title': 'File to use as glossary index',
-                    'pattern': '^[0-9a-zA-Z ... ]+$'
+                    'pattern': FILENAME_REGEX
                 },
                 'summary': {
                     'default': 'SUMMARY.md',
                     'type': 'string',
                     'title': 'File to use as table of contents',
-                    'pattern': '^[0-9a-zA-Z ... ]+$'
+                    'pattern': FILENAME_REGEX
                 }
             },
             'additionalProperties': false

lib/constants/defaultPlugins.js

@@ -1,9 +1,24 @@
 var Immutable = require('immutable');
+var PluginDependency = require('../models/pluginDependency');
+
+var pkg = require('../../package.json');
+
+/**
+ * Create a PluginDependency from a dependency of gitbook
+ * @param {String} pluginName
+ * @return {PluginDependency}
+ */
+function createFromDependency(pluginName) {
+    var npmID = PluginDependency.nameToNpmID(pluginName);
+    var version = pkg.dependencies[npmID];
+
+    return PluginDependency.create(pluginName, version);
+}
 
 /*
-    List of default plugins for all books,
-    default plugins should be installed in node dependencies of GitBook
-*/
+ * List of default plugins for all books,
+ * default plugins should be installed in node dependencies of GitBook
+ */
 module.exports = Immutable.List([
     'highlight',
     'search',
@@ -11,4 +26,4 @@ module.exports = Immutable.List([
     'sharing',
     'fontsettings',
     'theme-default'
-]);
+]).map(createFromDependency);

lib/constants/extsAsciidoc.js

@@ -0,0 +1,4 @@
+module.exports = [
+    '.adoc',
+    '.asciidoc'
+];

lib/constants/extsMarkdown.js

@@ -0,0 +1,5 @@
+module.exports = [
+    '.md',
+    '.markdown',
+    '.mdown'
+];

lib/constants/themePrefix.js

@@ -0,0 +1,4 @@
+/*
+    All GitBook themes plugins name start with this prefix once shorted.
+*/
+module.exports = 'theme-';

lib/models/__tests__/config.js

@@ -55,6 +55,36 @@ describe('Config', function() {
             expect(world).toBe(2);
         });
     });
+
+    describe('toReducedVersion', function() {
+        it('must only return diffs for simple values', function() {
+            var _config = Config.createWithValues({
+                gitbook: '3.0.0'
+            });
+
+            var reducedVersion = _config.toReducedVersion();
+
+            expect(reducedVersion.toJS()).toEqual({
+                gitbook: '3.0.0'
+            });
+        });
+
+        it('must only return diffs for deep values', function() {
+            var _config = Config.createWithValues({
+                structure: {
+                    readme: 'intro.md'
+                }
+            });
+
+            var reducedVersion = _config.toReducedVersion();
+
+            expect(reducedVersion.toJS()).toEqual({
+                structure: {
+                    readme: 'intro.md'
+                }
+            });
+        });
+    });
 });
 
 

lib/models/__tests__/page.js

@@ -0,0 +1,28 @@
+var Immutable = require('immutable');
+var Page = require('../page');
+
+describe('Page', function() {
+
+    describe('toText', function() {
+        it('must not prepend frontmatter if no attributes', function() {
+            var page = Page().merge({
+                content: 'Hello World'
+            });
+
+            expect(page.toText()).toBe('Hello World');
+        });
+
+        it('must prepend frontmatter if attributes', function() {
+            var page = Page().merge({
+                content: 'Hello World',
+                attributes: Immutable.fromJS({
+                    hello: 'world'
+                })
+            });
+
+            expect(page.toText()).toBe('---\nhello: world\n---\n\nHello World');
+        });
+    });
+});
+
+

lib/models/__tests__/pluginDependency.js

@@ -42,21 +42,39 @@ describe('PluginDependency', function() {
                 expect(plugin.getVersion()).toBe('git+ssh://samy@github.com/GitbookIO/plugin-ga.git');
             });
         });
-    });
 
-    describe('listToArray', function() {
-        var list = PluginDependency.listToArray(Immutable.List([
-            PluginDependency.createFromString('hello@1.0.0'),
-            PluginDependency.createFromString('noversion'),
-            PluginDependency.createFromString('-disabled')
-        ]));
+        describe('listToArray', function() {
+            it('must create an array from a list of plugin dependencies', function() {
+                var list = PluginDependency.listToArray(Immutable.List([
+                    PluginDependency.createFromString('hello@1.0.0'),
+                    PluginDependency.createFromString('noversion'),
+                    PluginDependency.createFromString('-disabled')
+                ]));
 
-        expect(list).toEqual([
-            'hello@1.0.0',
-            'noversion',
-            '-disabled'
-        ]);
+                expect(list).toEqual([
+                    'hello@1.0.0',
+                    'noversion',
+                    '-disabled'
+                ]);
+            });
+        });
+
+        describe('listFromArray', function() {
+            it('must create an array from a list of plugin dependencies', function() {
+                var arr = Immutable.fromJS([
+                    'hello@1.0.0',
+                    {
+                        'name': 'plugin-ga',
+                        'version': 'git+ssh://samy@github.com/GitbookIO/plugin-ga.git'
+                    }
+                ]);
+                var list = PluginDependency.listFromArray(arr);
+
+                expect(list.first().getName()).toBe('hello');
+                expect(list.first().getVersion()).toBe('1.0.0');
+                expect(list.last().getName()).toBe('plugin-ga');
+                expect(list.last().getVersion()).toBe('git+ssh://samy@github.com/GitbookIO/plugin-ga.git');
+            });
+        });
     });
 });
-
-

lib/models/__tests__/summaryArticle.js

@@ -0,0 +1,53 @@
+var SummaryArticle = require('../summaryArticle');
+var File = require('../file');
+
+describe('SummaryArticle', function() {
+    describe('createChildLevel', function() {
+        it('must create the right level', function() {
+            var article = SummaryArticle.create({}, '1.1');
+            expect(article.createChildLevel()).toBe('1.1.1');
+        });
+
+        it('must create the right level when has articles', function() {
+            var article = SummaryArticle.create({
+                articles: [
+                    {
+                        title: 'Test'
+                    }
+                ]
+            }, '1.1');
+            expect(article.createChildLevel()).toBe('1.1.2');
+        });
+    });
+
+    describe('isFile', function() {
+        it('must return true when exactly the file', function() {
+            var article = SummaryArticle.create({
+                ref: 'hello.md'
+            }, '1.1');
+            var file = File.createWithFilepath('hello.md');
+
+            expect(article.isFile(file)).toBe(true);
+        });
+
+        it('must return true when path is not normalized', function() {
+            var article = SummaryArticle.create({
+                ref: '/hello.md'
+            }, '1.1');
+            var file = File.createWithFilepath('hello.md');
+
+            expect(article.isFile(file)).toBe(true);
+        });
+
+        it('must return false when has anchor', function() {
+            var article = SummaryArticle.create({
+                ref: 'hello.md#world'
+            }, '1.1');
+            var file = File.createWithFilepath('hello.md');
+
+            expect(article.isFile(file)).toBe(false);
+        });
+    });
+});
+
+

lib/models/__tests__/summaryPart.js

@@ -0,0 +1,23 @@
+var SummaryPart = require('../summaryPart');
+
+describe('SummaryPart', function() {
+    describe('createChildLevel', function() {
+        it('must create the right level', function() {
+            var article = SummaryPart.create({}, '1');
+            expect(article.createChildLevel()).toBe('1.1');
+        });
+
+        it('must create the right level when has articles', function() {
+            var article = SummaryPart.create({
+                articles: [
+                    {
+                        title: 'Test'
+                    }
+                ]
+            }, '1');
+            expect(article.createChildLevel()).toBe('1.2');
+        });
+    });
+});
+
+

lib/models/book.js

@@ -293,26 +293,47 @@ Book.prototype.getDefaultExt = function() {
 
 /**
     Infer the default path for a Readme.
+    @param {Boolean} [absolute=false] False for a path relative to
+        this book's content root
     @return {String}
 */
-Book.prototype.getDefaultReadmePath = function() {
-    return this.getContentRoot()+'README'+this.getDefaultExt();
+Book.prototype.getDefaultReadmePath = function(absolute) {
+    var defaultPath = 'README'+this.getDefaultExt();
+    if (absolute) {
+        return path.join(this.getContentRoot(), defaultPath);
+    } else {
+        return defaultPath;
+    }
 };
 
 /**
     Infer the default path for a Summary.
+    @param {Boolean} [absolute=false] False for a path relative to
+        this book's content root
     @return {String}
 */
-Book.prototype.getDefaultSummaryPath = function() {
-    return this.getContentRoot()+'SUMMARY'+this.getDefaultExt();
+Book.prototype.getDefaultSummaryPath = function(absolute) {
+    var defaultPath = 'SUMMARY'+this.getDefaultExt();
+    if (absolute) {
+        return path.join(this.getContentRoot(), defaultPath);
+    } else {
+        return defaultPath;
+    }
 };
 
 /**
     Infer the default path for a Glossary.
+    @param {Boolean} [absolute=false] False for a path relative to
+        this book's content root
     @return {String}
 */
-Book.prototype.getDefaultGlossaryPath = function() {
-    return this.getContentRoot()+'GLOSSARY'+this.getDefaultExt();
+Book.prototype.getDefaultGlossaryPath = function(absolute) {
+    var defaultPath = 'GLOSSARY'+this.getDefaultExt();
+    if (absolute) {
+        return path.join(this.getContentRoot(), defaultPath);
+    } else {
+        return defaultPath;
+    }
 };
 
 /**
@@ -324,12 +345,16 @@ Book.prototype.getDefaultGlossaryPath = function() {
 */
 Book.createFromParent = function createFromParent(parent, language) {
     var ignore = parent.getIgnore();
+    var config = parent.getConfig();
+
+    // Set language in configuration
+    config = config.setValue('language', language);
 
     return new Book({
         // Inherits config. logegr and list of ignored files
         logger: parent.getLogger(),
-        config: parent.getConfig(),
-        ignore: Ignore().add(ignore),
+        config: config,
+        ignore: ignore,
 
         language: language,
         fs: FS.reduceScope(parent.getContentFS(), language)

lib/models/config.js

@@ -4,6 +4,7 @@ var Immutable = require('immutable');
 var File = require('./file');
 var PluginDependency = require('./pluginDependency');
 var configDefault = require('../constants/configDefault');
+var reducedObject = require('../utils/reducedObject');
 
 var Config = Immutable.Record({
     file:       File(),
@@ -19,21 +20,36 @@ Config.prototype.getValues = function() {
 };
 
 /**
-    Change the file for the configuration
+ * Return minimum version of configuration,
+ * Basically it returns the current config minus the default one
+ * @return {Map}
+ */
+Config.prototype.toReducedVersion = function() {
+    return reducedObject(configDefault, this.getValues());
+};
 
-    @param {File} file
-    @return {Config}
-*/
+/**
+ * Render config as text
+ * @return {Promise<String>}
+ */
+Config.prototype.toText = function() {
+    return JSON.stringify(this.toReducedVersion().toJS(), null, 4);
+};
+
+/**
+ * Change the file for the configuration
+ * @param {File} file
+ * @return {Config}
+ */
 Config.prototype.setFile = function(file) {
     return this.set('file', file);
 };
 
 /**
-    Return a configuration value by its key path
-
-    @param {String} key
-    @return {Mixed}
-*/
+ * Return a configuration value by its key path
+ * @param {String} key
+ * @return {Mixed}
+ */
 Config.prototype.getValue = function(keyPath, def) {
     var values = this.getValues();
     keyPath = Config.keyToKeyPath(keyPath);
@@ -46,12 +62,11 @@ Config.prototype.getValue = function(keyPath, def) {
 };
 
 /**
-    Update a configuration value
-
-    @param {String} key
-    @param {Mixed} value
-    @return {Config}
-*/
+ * Update a configuration value
+ * @param {String} key
+ * @param {Mixed} value
+ * @return {Config}
+ */
 Config.prototype.setValue = function(keyPath, value) {
     keyPath = Config.keyToKeyPath(keyPath);
 
@@ -64,10 +79,9 @@ Config.prototype.setValue = function(keyPath, value) {
 };
 
 /**
-    Return a list of plugin dependencies
-
-    @return {List<PluginDependency>}
-*/
+ * Return a list of plugin dependencies
+ * @return {List<PluginDependency>}
+ */
 Config.prototype.getPluginDependencies = function() {
     var plugins = this.getValue('plugins');
 
@@ -79,11 +93,10 @@ Config.prototype.getPluginDependencies = function() {
 };
 
 /**
-    Return a plugin dependency by its name
-
-    @param {String} name
-    @return {PluginDependency}
-*/
+ * Return a plugin dependency by its name
+ * @param {String} name
+ * @return {PluginDependency}
+ */
 Config.prototype.getPluginDependency = function(name) {
     var plugins = this.getPluginDependencies();
 
@@ -93,11 +106,10 @@ Config.prototype.getPluginDependency = function(name) {
 };
 
 /**
-    Update the list of plugins dependencies
-
-    @param {List<PluginDependency>}
-    @return {Config}
-*/
+ * Update the list of plugins dependencies
+ * @param {List<PluginDependency>}
+ * @return {Config}
+ */
 Config.prototype.setPluginDependencies = function(deps) {
     var plugins = PluginDependency.listToArray(deps);
 
@@ -106,11 +118,10 @@ Config.prototype.setPluginDependencies = function(deps) {
 
 
 /**
-    Update values for an existing configuration
-
-    @param {Object} values
-    @returns {Config}
-*/
+ * Update values for an existing configuration
+ * @param {Object} values
+ * @returns {Config}
+ */
 Config.prototype.updateValues = function(values) {
     values = Immutable.fromJS(values);
 
@@ -118,12 +129,11 @@ Config.prototype.updateValues = function(values) {
 };
 
 /**
-    Update values for an existing configuration
-
-    @param {Config} config
-    @param {Object} values
-    @returns {Config}
-*/
+ * Update values for an existing configuration
+ * @param {Config} config
+ * @param {Object} values
+ * @returns {Config}
+ */
 Config.prototype.mergeValues = function(values) {
     var currentValues = this.getValues();
     values = Immutable.fromJS(values);
@@ -134,12 +144,11 @@ Config.prototype.mergeValues = function(values) {
 };
 
 /**
-    Create a new config for a file
-
-    @param {File} file
-    @param {Object} values
-    @returns {Config}
-*/
+ * Create a new config for a file
+ * @param {File} file
+ * @param {Object} values
+ * @returns {Config}
+ */
 Config.create = function(file, values) {
     return new Config({
         file: file,
@@ -148,11 +157,10 @@ Config.create = function(file, values) {
 };
 
 /**
-    Create a new config
-
-    @param {Object} values
-    @returns {Config}
-*/
+ * Create a new config
+ * @param {Object} values
+ * @returns {Config}
+ */
 Config.createWithValues = function(values) {
     return new Config({
         values: Immutable.fromJS(values)
@@ -161,11 +169,10 @@ Config.createWithValues = function(values) {
 
 
 /**
-    Convert a keyPath to an array of keys
-
-    @param {String|Array}
-    @return {Array}
-*/
+ * Convert a keyPath to an array of keys
+ * @param {String|Array}
+ * @return {Array}
+ */
 Config.keyToKeyPath = function(keyPath) {
     if (is.string(keyPath)) keyPath = keyPath.split('.');
     return keyPath;

lib/models/fs.js

@@ -229,7 +229,7 @@ FS.prototype.listAllFiles = function(dirName, filterFn) {
 };
 
 /**
-    Find a file in a folder (case incensitive)
+    Find a file in a folder (case insensitive)
     Return the found filename
 
     @param {String} dirname

lib/models/page.js

@@ -1,4 +1,5 @@
 var Immutable = require('immutable');
+var yaml = require('js-yaml');
 
 var File = require('./file');
 
@@ -32,19 +33,33 @@ Page.prototype.getDir = function() {
 };
 
 /**
-    Return path of the page
+ * Return page as text
+ * @return {String}
+*/
+Page.prototype.toText = function() {
+    var attrs = this.getAttributes();
+    var content = this.getContent();
 
-    @return {String}
+    if (attrs.size === 0) {
+        return content;
+    }
+
+    var frontMatter = '---\n' + yaml.safeDump(attrs.toJS(), { skipInvalid: true }) + '---\n\n';
+    return (frontMatter + content);
+};
+
+/**
+ * Return path of the page
+ * @return {String}
 */
 Page.prototype.getPath = function() {
     return this.getFile().getPath();
 };
 
 /**
-    Create a page for a file
-
-    @param {File} file
-    @return {Page}
+ * Create a page for a file
+ * @param {File} file
+ * @return {Page}
 */
 Page.createForFile = function(file) {
     return new Page({

lib/models/parser.js

@@ -55,6 +55,11 @@ Parser.prototype.parsePage = function(content) {
     return Promise(page(content));
 };
 
+Parser.prototype.parseInline = function(content) {
+    var inline = this.get('inline');
+    return Promise(inline(content));
+};
+
 Parser.prototype.parseLanguages = function(content) {
     var langs = this.get('langs');
     return Promise(langs(content));

lib/models/plugin.js

@@ -1,7 +1,9 @@
 var Immutable = require('immutable');
 
 var TemplateBlock = require('./templateBlock');
-var PREFIX = require('../constants/pluginPrefix');
+var PluginDependency = require('./pluginDependency');
+var THEME_PREFIX = require('../constants/themePrefix');
+
 var DEFAULT_VERSION = '*';
 
 var Plugin = Immutable.Record({
@@ -16,6 +18,9 @@ var Plugin = Immutable.Record({
     // Depth of this plugin in the dependency tree
     depth:      Number(0),
 
+    // Parent depending on this plugin
+    parent:     String(),
+
     // Content of the "package.json"
     package:    Immutable.Map(),
 
@@ -47,38 +52,48 @@ Plugin.prototype.getDepth = function() {
     return this.get('depth');
 };
 
-/**
-    Return the ID on NPM for this plugin
-
-    @return {String}
-*/
-Plugin.prototype.getNpmID = function() {
-    return Plugin.nameToNpmID(this.getName());
+Plugin.prototype.getParent = function() {
+    return this.get('parent');
 };
 
 /**
-    Check if a plugin is loaded
+ * Return the ID on NPM for this plugin
+ * @return {String}
+ */
+Plugin.prototype.getNpmID = function() {
+    return PluginDependency.nameToNpmID(this.getName());
+};
 
-    @return {Boolean}
-*/
+/**
+ * Check if a plugin is loaded
+ * @return {Boolean}
+ */
 Plugin.prototype.isLoaded = function() {
     return Boolean(this.getPackage().size > 0);
 };
 
 /**
-    Return map of hooks
-    @return {Map<String:Function>}
-*/
+ * Check if a plugin is a theme given its name
+ * @return {Boolean}
+ */
+Plugin.prototype.isTheme = function() {
+    var name = this.getName();
+    return (name && name.indexOf(THEME_PREFIX) === 0);
+};
+
+/**
+ * Return map of hooks
+ * @return {Map<String:Function>}
+ */
 Plugin.prototype.getHooks = function() {
     return this.getContent().get('hooks') || Immutable.Map();
 };
 
 /**
-    Return infos about resources for a specific type
-
-    @param {String} type
-    @return {Map<String:Mixed>}
-*/
+ * Return infos about resources for a specific type
+ * @param {String} type
+ * @return {Map<String:Mixed>}
+ */
 Plugin.prototype.getResources = function(type) {
     if (type != 'website' && type != 'ebook') {
         throw new Error('Invalid assets type ' + type);
@@ -91,17 +106,17 @@ Plugin.prototype.getResources = function(type) {
 };
 
 /**
-    Return map of filters
-    @return {Map<String:Function>}
-*/
+ * Return map of filters
+ * @return {Map<String:Function>}
+ */
 Plugin.prototype.getFilters = function() {
     return this.getContent().get('filters');
 };
 
 /**
-    Return map of blocks
-    @return {Map<String:TemplateBlock>}
-*/
+ * Return map of blocks
+ * @return {Map<String:TemplateBlock>}
+ */
 Plugin.prototype.getBlocks = function() {
     var blocks = this.getContent().get('blocks');
     blocks = blocks || Immutable.Map();
@@ -113,21 +128,19 @@ Plugin.prototype.getBlocks = function() {
 };
 
 /**
-    Return a specific hook
-
-    @param {String} name
-    @return {Function|undefined}
-*/
+ * Return a specific hook
+ * @param {String} name
+ * @return {Function|undefined}
+ */
 Plugin.prototype.getHook = function(name) {
     return this.getHooks().get(name);
 };
 
 /**
-    Create a plugin from a string
-
-    @param {String}
-    @return {Plugin}
-*/
+ * Create a plugin from a string
+ * @param {String}
+ * @return {Plugin}
+ */
 Plugin.createFromString = function(s) {
     var parts = s.split('@');
     var name = parts[0];
@@ -140,11 +153,10 @@ Plugin.createFromString = function(s) {
 };
 
 /**
-    Create a plugin from a dependency
-
-    @param {PluginDependency}
-    @return {Plugin}
-*/
+ * Create a plugin from a dependency
+ * @param {PluginDependency}
+ * @return {Plugin}
+ */
 Plugin.createFromDep = function(dep) {
     return new Plugin({
         name: dep.getName(),
@@ -152,14 +164,6 @@ Plugin.createFromDep = function(dep) {
     });
 };
 
-/**
-    Return NPM id for a plugin name
-
-    @param {String}
-    @return {String}
-*/
-Plugin.nameToNpmID = function(s) {
-    return PREFIX + s;
-};
+Plugin.nameToNpmID = PluginDependency.nameToNpmID;
 
 module.exports = Plugin;

lib/models/pluginDependency.js

@@ -1,12 +1,14 @@
 var is = require('is');
+var semver = require('semver');
 var Immutable = require('immutable');
 
+var PREFIX = require('../constants/pluginPrefix');
 var DEFAULT_VERSION = '*';
 
 /*
-    PluginDependency represents the informations about a plugin
-    stored in config.plugins
-*/
+ * PluginDependency represents the informations about a plugin
+ * stored in config.plugins
+ */
 var PluginDependency = Immutable.Record({
     name:       String(),
 
@@ -30,11 +32,39 @@ PluginDependency.prototype.isEnabled = function() {
 };
 
 /**
-    Create a plugin with a name and a plugin
+ * Toggle this plugin state
+ * @param  {Boolean}
+ * @return {PluginDependency}
+ */
+PluginDependency.prototype.toggle = function(state) {
+    if (is.undef(state)) {
+        state = !this.isEnabled();
+    }
 
-    @param {String}
-    @return {Plugin|undefined}
-*/
+    return this.set('enabled', state);
+};
+
+/**
+ * Return NPM ID for the dependency
+ * @return {String}
+ */
+PluginDependency.prototype.getNpmID = function() {
+    return PluginDependency.nameToNpmID(this.getName());
+};
+
+/**
+ * Is the plugin using a git dependency
+ * @return {Boolean}
+ */
+PluginDependency.prototype.isGitDependency = function() {
+    return !semver.validRange(this.getVersion());
+};
+
+/**
+ * Create a plugin with a name and a plugin
+ * @param {String}
+ * @return {Plugin|undefined}
+ */
 PluginDependency.create = function(name, version, enabled) {
     if (is.undefined(enabled)) {
         enabled = true;
@@ -48,11 +78,10 @@ PluginDependency.create = function(name, version, enabled) {
 };
 
 /**
-    Create a plugin from a string
-
-    @param {String}
-    @return {Plugin|undefined}
-*/
+ * Create a plugin from a string
+ * @param {String}
+ * @return {Plugin|undefined}
+ */
 PluginDependency.createFromString = function(s) {
     var parts = s.split('@');
     var name = parts[0];
@@ -72,22 +101,20 @@ PluginDependency.createFromString = function(s) {
 };
 
 /**
-    Create a PluginDependency from a string
-
-    @param {String}
-    @return {List<PluginDependency>}
-*/
+ * Create a PluginDependency from a string
+ * @param {String}
+ * @return {List<PluginDependency>}
+ */
 PluginDependency.listFromString = function(s) {
     var parts = s.split(',');
     return PluginDependency.listFromArray(parts);
 };
 
 /**
-    Create a PluginDependency from an array
-
-    @param {Array}
-    @return {List<PluginDependency>}
-*/
+ * Create a PluginDependency from an array
+ * @param {Array}
+ * @return {List<PluginDependency>}
+ */
 PluginDependency.listFromArray = function(arr) {
     return Immutable.List(arr)
         .map(function(entry) {
@@ -95,8 +122,8 @@ PluginDependency.listFromArray = function(arr) {
                 return PluginDependency.createFromString(entry);
             } else {
                 return PluginDependency({
-                    name: entry.name,
-                    version: entry.version
+                    name: entry.get('name'),
+                    version: entry.get('version')
                 });
             }
         })
@@ -106,11 +133,10 @@ PluginDependency.listFromArray = function(arr) {
 };
 
 /**
-    Export plugin dependencies as an array
-
-    @param {List<PluginDependency>} list
-    @return {Array<String>}
-*/
+ * Export plugin dependencies as an array
+ * @param {List<PluginDependency>} list
+ * @return {Array<String>}
+ */
 PluginDependency.listToArray = function(list) {
     return list
         .map(function(dep) {
@@ -130,4 +156,13 @@ PluginDependency.listToArray = function(list) {
         .toJS();
 };
 
+/**
+ * Return NPM id for a plugin name
+ * @param {String}
+ * @return {String}
+ */
+PluginDependency.nameToNpmID = function(s) {
+    return PREFIX + s;
+};
+
 module.exports = PluginDependency;

lib/models/summaryArticle.js

@@ -30,20 +30,21 @@ SummaryArticle.prototype.getArticles = function() {
 };
 
 /**
-    Return how deep the article is.
-    The README has a depth of 1
-
-    @return {Number}
-*/
+ * Return how deep the article is.
+ * The README has a depth of 1
+ *
+ * @return {Number}
+ */
 SummaryArticle.prototype.getDepth = function() {
     return (this.getLevel().split('.').length - 1);
 };
 
 /**
-    Get path (without anchor) to the pointing file
-
-    @return {String}
-*/
+ * Get path (without anchor) to the pointing file.
+ * It also normalizes the file path.
+ *
+ * @return {String}
+ */
 SummaryArticle.prototype.getPath = function() {
     if (this.isExternal()) {
         return undefined;
@@ -58,24 +59,24 @@ SummaryArticle.prototype.getPath = function() {
 
     var pathname = (parts.length > 1? parts.slice(0, -1).join('#') : ref);
 
-    // Normalize path to remove ('./', etc)
-    return location.normalize(pathname);
+    // Normalize path to remove ('./', '/...', etc)
+    return location.flatten(pathname);
 };
 
 /**
-    Return url if article is external
-
-    @return {String}
-*/
+ * Return url if article is external
+ *
+ * @return {String}
+ */
 SummaryArticle.prototype.getUrl = function() {
     return this.isExternal()? this.getRef() : undefined;
 };
 
 /**
-    Get anchor for this article (or undefined)
-
-    @return {String}
-*/
+ * Get anchor for this article (or undefined)
+ *
+ * @return {String}
+ */
 SummaryArticle.prototype.getAnchor = function() {
     var ref = this.getRef();
     var parts = ref.split('#');
@@ -85,29 +86,68 @@ SummaryArticle.prototype.getAnchor = function() {
 };
 
 /**
-    Is article pointing to a page of an absolute url
+ * Create a new level for a new child article
+ *
+ * @return {String}
+ */
+SummaryArticle.prototype.createChildLevel = function() {
+    var level       = this.getLevel();
+    var subArticles = this.getArticles();
+    var childLevel  = level + '.' + (subArticles.size + 1);
 
-    @return {Boolean}
-*/
+    return childLevel;
+};
+
+/**
+ * Is article pointing to a page of an absolute url
+ *
+ * @return {Boolean}
+ */
 SummaryArticle.prototype.isPage = function() {
     return !this.isExternal() && this.getRef();
 };
 
 /**
-    Is article pointing to aan absolute url
+ * Check if this article is a file (exatcly)
+ *
+ * @param {File} file
+ * @return {Boolean}
+ */
+SummaryArticle.prototype.isFile = function(file) {
+    return (
+        file.getPath() === this.getPath()
+        && this.getAnchor() === undefined
+    );
+};
 
-    @return {Boolean}
-*/
+/**
+ * Check if this article is the introduction of the book
+ *
+ * @param {Book|Readme} book
+ * @return {Boolean}
+ */
+SummaryArticle.prototype.isReadme = function(book) {
+    var readme = book.getFile? book : book.getReadme();
+    var file = readme.getFile();
+
+    return this.isFile(file);
+};
+
+/**
+ * Is article pointing to aan absolute url
+ *
+ * @return {Boolean}
+ */
 SummaryArticle.prototype.isExternal = function() {
     return location.isExternal(this.getRef());
 };
 
 /**
-    Create a SummaryArticle
-
-    @param {Object} def
-    @return {SummaryArticle}
-*/
+ * Create a SummaryArticle
+ *
+ * @param {Object} def
+ * @return {SummaryArticle}
+ */
 SummaryArticle.create = function(def, level) {
     var articles = (def.articles || []).map(function(article, i) {
         if (article instanceof SummaryArticle) {
@@ -124,14 +164,13 @@ SummaryArticle.create = function(def, level) {
     });
 };
 
-
 /**
-    Find an article from a base one
-
-    @param {Article|Part} base
-    @param {Function(article)} iter
-    @return {Article}
-*/
+ * Find an article from a base one
+ *
+ * @param {Article|Part} base
+ * @param {Function(article)} iter
+ * @return {Article}
+ */
 SummaryArticle.findArticle = function(base, iter) {
     var articles = base.getArticles();
 

lib/models/summaryPart.js

@@ -25,11 +25,24 @@ SummaryPart.prototype.getArticles = function() {
 };
 
 /**
-    Create a SummaryPart
+ * Create a new level for a new child article
+ *
+ * @return {String}
+ */
+SummaryPart.prototype.createChildLevel = function() {
+    var level       = this.getLevel();
+    var subArticles = this.getArticles();
+    var childLevel  = level + '.' + (subArticles.size + 1);
 
-    @param {Object} def
-    @return {SummaryPart}
-*/
+    return childLevel;
+};
+
+/**
+ * Create a SummaryPart
+ *
+ * @param {Object} def
+ * @return {SummaryPart}
+ */
 SummaryPart.create = function(def, level) {
     var articles = (def.articles || []).map(function(article, i) {
         if (article instanceof SummaryArticle) {

lib/models/templateBlock.js

@@ -43,10 +43,9 @@ TemplateBlock.prototype.getBlocks = function() {
 
 
 /**
-    Return shortcuts associated with this block or undefined
-
-    @return {TemplateShortcut|undefined}
-*/
+ * Return shortcuts associated with this block or undefined
+ * @return {TemplateShortcut|undefined}
+ */
 TemplateBlock.prototype.getShortcuts = function() {
     var shortcuts = this.get('shortcuts');
     if (shortcuts.size === 0) {
@@ -57,19 +56,17 @@ TemplateBlock.prototype.getShortcuts = function() {
 };
 
 /**
-    Return name for the nunjucks extension
-
-    @return {String}
-*/
+ * Return name for the nunjucks extension
+ * @return {String}
+ */
 TemplateBlock.prototype.getExtensionName = function() {
     return 'Block' + this.getName() + 'Extension';
 };
 
 /**
-    Return a nunjucks extension to represents this block
-
-    @return {Nunjucks.Extension}
-*/
+ * Return a nunjucks extension to represents this block
+ * @return {Nunjucks.Extension}
+ */
 TemplateBlock.prototype.toNunjucksExt = function(mainContext, blocksOutput) {
     blocksOutput = blocksOutput || {};
 
@@ -192,11 +189,11 @@ TemplateBlock.prototype.toNunjucksExt = function(mainContext, blocksOutput) {
 };
 
 /**
-    Apply a block to a content
-    @param {Object} inner
-    @param {Object} context
-    @return {Promise<String>|String}
-*/
+ * Apply a block to a content
+ * @param {Object} inner
+ * @param {Object} context
+ * @return {Promise<String>|String}
+ */
 TemplateBlock.prototype.applyBlock = function(inner, context) {
     var processFn = this.getProcess();
 
@@ -215,11 +212,10 @@ TemplateBlock.prototype.applyBlock = function(inner, context) {
 };
 
 /**
-    Normalize result from a block process function
-
-    @param {Object|String} result
-    @return {Object}
-*/
+ * Normalize result from a block process function
+ * @param {Object|String} result
+ * @return {Object}
+ */
 TemplateBlock.prototype.normalizeBlockResult = function(result) {
     if (is.string(result)) {
         result = { body: result };
@@ -230,12 +226,11 @@ TemplateBlock.prototype.normalizeBlockResult = function(result) {
 };
 
 /**
-    Convert a block result to HTML
-
-    @param {Object} result
-    @param {Object} blocksOutput: stored post processing blocks in this object
-    @return {String}
-*/
+ * Convert a block result to HTML
+ * @param {Object} result
+ * @param {Object} blocksOutput: stored post processing blocks in this object
+ * @return {String}
+ */
 TemplateBlock.prototype.blockResultToHtml = function(result, blocksOutput) {
     var indexedKey;
     var toIndex = (!result.parse) || (result.post !== undefined);
@@ -256,12 +251,11 @@ TemplateBlock.prototype.blockResultToHtml = function(result, blocksOutput) {
 };
 
 /**
-    Create a template block from a function or an object
-
-    @param {String} blockName
-    @param {Object} block
-    @return {TemplateBlock}
-*/
+ * Create a template block from a function or an object
+ * @param {String} blockName
+ * @param {Object} block
+ * @return {TemplateBlock}
+ */
 TemplateBlock.create = function(blockName, block) {
     if (is.fn(block)) {
         block = new Immutable.Map({
@@ -275,11 +269,10 @@ TemplateBlock.create = function(blockName, block) {
 };
 
 /**
-    Extract kwargs from an arguments array
-
-    @param {Array} args
-    @return {Object}
-*/
+ * Extract kwargs from an arguments array
+ * @param {Array} args
+ * @return {Object}
+ */
 function extractKwargs(args) {
     var last = args[args.length - 1];
     return (is.object(last) && last.__keywords)? args.pop() : {};

lib/models/templateOutput.js

@@ -17,23 +17,21 @@ TemplateOutput.prototype.getBlocks = function() {
 };
 
 /**
-    Update content of this output
-
-    @param {String} content
-    @return {TemplateContent}
-*/
+ * Update content of this output
+ * @param {String} content
+ * @return {TemplateContent}
+ */
 TemplateOutput.prototype.setContent = function(content) {
     return this.set('content', content);
 };
 
 /**
-    Create a TemplateOutput from a text content
-    and an object containing block definition
-
-    @param {String} content
-    @param {Object} blocks
-    @return {TemplateOutput}
-*/
+ * Create a TemplateOutput from a text content
+ * and an object containing block definition
+ * @param {String} content
+ * @param {Object} blocks
+ * @return {TemplateOutput}
+ */
 TemplateOutput.create = function(content, blocks) {
     return new TemplateOutput({
         content:    content,

lib/modifiers/config/__tests__/addPlugin.js

@@ -1,12 +1,10 @@
 var addPlugin = require('../addPlugin');
 var Config = require('../../../models/config');
-var Book = require('../../../models/book');
 
 describe('addPlugin', function() {
     var config = Config.createWithValues({
         plugins: ['hello', 'world', '-disabled']
     });
-    var book = Book().setConfig(config);
 
     it('should have correct state of dependencies', function() {
         var disabledDep = config.getPluginDependency('disabled');
@@ -17,8 +15,7 @@ describe('addPlugin', function() {
     });
 
     it('should add the plugin to the list', function() {
-        var newBook = addPlugin(book, 'test');
-        var newConfig = newBook.getConfig();
+        var newConfig = addPlugin(config, 'test');
 
         var testDep = newConfig.getPluginDependency('test');
         expect(testDep).toBeDefined();

lib/modifiers/config/__tests__/removePlugin.js

@@ -0,0 +1,33 @@
+var removePlugin = require('../removePlugin');
+var Config = require('../../../models/config');
+
+describe('removePlugin', function() {
+    var config = Config.createWithValues({
+        plugins: ['hello', 'world', '-disabled']
+    });
+
+    it('should remove the plugin from the list', function() {
+        var newConfig = removePlugin(config, 'hello');
+
+        var testDep = newConfig.getPluginDependency('hello');
+        expect(testDep).toNotBeDefined();
+    });
+
+    it('should remove the disabled plugin from the list', function() {
+        var newConfig = removePlugin(config, 'disabled');
+
+        var testDep = newConfig.getPluginDependency('disabled');
+        expect(testDep).toNotBeDefined();
+    });
+
+    it('should disable default plugin', function() {
+        var newConfig = removePlugin(config, 'search');
+
+        var disabledDep = newConfig.getPluginDependency('search');
+        expect(disabledDep).toBeDefined();
+        expect(disabledDep.getVersion()).toEqual('*');
+        expect(disabledDep.isEnabled()).toBeFalsy();
+    });
+});
+
+

lib/modifiers/config/__tests__/togglePlugin.js

@@ -0,0 +1,28 @@
+var togglePlugin = require('../togglePlugin');
+var Config = require('../../../models/config');
+
+describe('togglePlugin', function() {
+    var config = Config.createWithValues({
+        plugins: ['hello', 'world', '-disabled']
+    });
+
+    it('should enable plugin', function() {
+        var newConfig = togglePlugin(config, 'disabled');
+
+        var testDep = newConfig.getPluginDependency('disabled');
+        expect(testDep).toBeDefined();
+        expect(testDep.getVersion()).toEqual('*');
+        expect(testDep.isEnabled()).toBeTruthy();
+    });
+
+    it('should disable plugin', function() {
+        var newConfig = togglePlugin(config, 'world');
+
+        var testDep = newConfig.getPluginDependency('world');
+        expect(testDep).toBeDefined();
+        expect(testDep.getVersion()).toEqual('*');
+        expect(testDep.isEnabled()).toBeFalsy();
+    });
+});
+
+

lib/modifiers/config/addPlugin.js

@@ -1,22 +1,25 @@
 var PluginDependency = require('../../models/pluginDependency');
+var togglePlugin = require('./togglePlugin');
+var isDefaultPlugin = require('./isDefaultPlugin');
+
 /**
-    Add a plugin to a book's configuration
+ * Add a plugin to a book's configuration
+ * @param {Config} config
+ * @param {String} pluginName
+ * @param {String} version (optional)
+ * @return {Config}
+ */
+function addPlugin(config, pluginName, version) {
+    // For default plugin, we only ensure it is enabled
+    if (isDefaultPlugin(pluginName, version)) {
+        return togglePlugin(config, pluginName, true);
+    }
 
-    @param {Book} book
-    @param {String} plugin
-    @param {String} version (optional)
-    @return {Book}
-*/
-function addPlugin(book, plugin, version) {
-    var config = book.getConfig();
     var deps = config.getPluginDependencies();
-
-    var dep = PluginDependency.create(plugin, version);
+    var dep = PluginDependency.create(pluginName, version);
 
     deps = deps.push(dep);
-    config = config.setPluginDependencies(deps);
-
-    return book.setConfig(config);
+    return config.setPluginDependencies(deps);
 }
 
 module.exports = addPlugin;

lib/modifiers/config/editPlugin.js

@@ -0,0 +1,13 @@
+
+/**
+ * Edit configuration of a plugin
+ * @param {Config} config
+ * @param {String} plugin
+ * @param {Object} pluginConfig
+ * @return {Config}
+ */
+function editPlugin(config, pluginName, pluginConfig) {
+    return config.set('pluginsConfig.'+pluginName, pluginConfig);
+}
+
+module.exports = editPlugin;

lib/modifiers/config/hasPlugin.js

@@ -0,0 +1,15 @@
+
+/**
+ * Test if a plugin is listed
+ * @param { {List<PluginDependency}} deps
+ * @param {String} plugin
+ * @param {String} version
+ * @return {Boolean}
+ */
+function hasPlugin(deps, pluginName, version) {
+    return !!deps.find(function(dep) {
+        return dep.getName() === pluginName && (!version || dep.getVersion() === version);
+    });
+}
+
+module.exports = hasPlugin;

lib/modifiers/config/index.js

@@ -1,5 +1,9 @@
 
 module.exports = {
-    addPlugin:          require('./addPlugin'),
-    removePlugin:       require('./removePlugin')
+    addPlugin:       require('./addPlugin'),
+    removePlugin:    require('./removePlugin'),
+    togglePlugin:    require('./togglePlugin'),
+    editPlugin:      require('./editPlugin'),
+    hasPlugin:       require('./hasPlugin'),
+    isDefaultPlugin: require('./isDefaultPlugin')
 };

lib/modifiers/config/isDefaultPlugin.js

@@ -0,0 +1,14 @@
+var DEFAULT_PLUGINS = require('../../constants/defaultPlugins');
+var hasPlugin = require('./hasPlugin');
+
+/**
+ * Test if a plugin is a default one
+ * @param {String} plugin
+ * @param {String} version
+ * @return {Boolean}
+ */
+function isDefaultPlugin(pluginName, version) {
+    return hasPlugin(DEFAULT_PLUGINS, pluginName, version);
+}
+
+module.exports = isDefaultPlugin;

lib/modifiers/config/removePlugin.js

@@ -1,22 +1,25 @@
+var togglePlugin = require('./togglePlugin');
+var isDefaultPlugin = require('./isDefaultPlugin');
 
 /**
-    Remove a plugin from a book's configuration
-
-    @param {Book} book
-    @param {String} plugin
-    @return {Book}
-*/
-function removePlugin(book, pluginName) {
-    var config = book.getConfig();
+ * Remove a plugin from a book's configuration
+ * @param {Config} config
+ * @param {String} plugin
+ * @return {Config}
+ */
+function removePlugin(config, pluginName) {
     var deps = config.getPluginDependencies();
 
+    // For default plugin, we have to disable it instead of removing from the list
+    if (isDefaultPlugin(pluginName)) {
+        return togglePlugin(config, pluginName, false);
+    }
 
-    deps = deps.filter(function(dep) {
+    // Remove the dependency from the list
+    deps = deps.filterNot(function(dep) {
         return dep.getName() === pluginName;
     });
-    config = config.setPluginDependencies(deps);
-
-    return book.setConfig(config);
+    return config.setPluginDependencies(deps);
 }
 
 module.exports = removePlugin;

lib/modifiers/config/togglePlugin.js

@@ -0,0 +1,31 @@
+var PluginDependency = require('../../models/pluginDependency');
+var hasPlugin = require('./hasPlugin');
+var isDefaultPlugin = require('./isDefaultPlugin');
+
+/**
+ * Enable/disable a plugin dependency
+ * @param {Config} config
+ * @param {String} pluginName
+ * @param {Boolean} state (optional)
+ * @return {Config}
+ */
+function togglePlugin(config, pluginName, state) {
+    var deps = config.getPluginDependencies();
+
+    // For default plugin, we should ensure it's listed first
+    if (isDefaultPlugin(pluginName) && !hasPlugin(deps, pluginName)) {
+        deps = deps.push(PluginDependency.create(pluginName));
+    }
+
+    deps = deps.map(function(dep) {
+        if (dep.getName() === pluginName) {
+            return dep.toggle(state);
+        }
+
+        return dep;
+    });
+
+    return config.setPluginDependencies(deps);
+}
+
+module.exports = togglePlugin;

lib/modifiers/summary/__tests__/insertPart.js

@@ -0,0 +1,60 @@
+var Summary = require('../../../models/summary');
+var SummaryPart = require('../../../models/summaryPart');
+
+var File = require('../../../models/file');
+
+describe('insertPart', function() {
+    var insertPart = require('../insertPart');
+    var summary = Summary.createFromParts(File(), [
+        {
+            articles: [
+                {
+                    title: '1.1',
+                    path: '1.1'
+                }
+            ]
+        },
+        {
+            title: 'Part I',
+            articles: [
+                {
+                    title: '2.1',
+                    path: '2.1',
+                    articles: []
+                },
+                {
+                    title: '2.2',
+                    path: '2.2'
+                }
+            ]
+        }
+    ]);
+
+    it('should insert an part at a given level', function() {
+        var part = SummaryPart.create({
+            title: 'Inserted'
+        }, 'meaningless.level');
+
+        var newSummary = insertPart(summary, part, 1);
+
+        var inserted = newSummary.getPart(1);
+        expect(inserted.getTitle()).toBe('Inserted');
+        expect(newSummary.getParts().count()).toBe(3);
+
+        var otherArticle = newSummary.getByLevel('3.1');
+        expect(otherArticle.getTitle()).toBe('2.1');
+        expect(otherArticle.getLevel()).toBe('3.1');
+    });
+
+    it('should insert an part in last position', function() {
+        var part = SummaryPart.create({
+            title: 'Inserted'
+        }, 'meaningless.level');
+
+        var newSummary = insertPart(summary, part, 2);
+
+        var inserted = newSummary.getPart(2);
+        expect(inserted.getTitle()).toBe('Inserted');
+        expect(newSummary.getParts().count()).toBe(3);
+    });
+});

lib/output/__tests__/website.js

@@ -1,3 +1,4 @@
+var fs = require('fs');
 var generateMock = require('../generateMock');
 var WebsiteGenerator = require('../website');
 
@@ -12,6 +13,54 @@ describe('WebsiteGenerator', function() {
         });
     });
 
+    describe('Glossary', function() {
+        var folder;
+
+        before(function() {
+            return generateMock(WebsiteGenerator, {
+                'README.md': 'Hello World',
+                'SUMMARY.md': '* [Deep](folder/page.md)',
+                'folder': {
+                    'page.md': 'Hello World'
+                },
+                'GLOSSARY.md': '# Glossary\n\n## Hello\n\nHello World'
+            })
+            .then(function(_folder) {
+                folder = _folder;
+            });
+        });
+
+        it('should generate a GLOSSARY.html', function() {
+            expect(folder).toHaveFile('GLOSSARY.html');
+        });
+
+        it('should correctly resolve glossary links in README', function() {
+            var html = fs.readFileSync(folder + '/index.html', 'utf8');
+            expect(html).toHaveDOMElement('.page-inner a[href="GLOSSARY.html#hello"]');
+        });
+
+        it('should correctly resolve glossary links in directory', function() {
+            var html = fs.readFileSync(folder + '/folder/page.html', 'utf8');
+            expect(html).toHaveDOMElement('.page-inner a[href="../GLOSSARY.html#hello"]');
+        });
+
+        it('should accept a custom glossary file', function() {
+            return generateMock(WebsiteGenerator, {
+                'README.md': 'Hello World',
+                'book.json': '{ "structure": { "glossary": "custom.md" } }',
+                'custom.md': '# Glossary\n\n## Hello\n\nHello World'
+            })
+            .then(function(folder) {
+                expect(folder).toHaveFile('custom.html');
+                expect(folder).toNotHaveFile('GLOSSARY.html');
+
+                var html = fs.readFileSync(folder + '/index.html', 'utf8');
+                expect(html).toHaveDOMElement('.page-inner a[href="custom.html#hello"]');
+            });
+        });
+    });
+
+
     it('should copy asset files', function() {
         return generateMock(WebsiteGenerator, {
             'README.md': 'Hello World',

lib/output/generateMock.js

@@ -19,7 +19,13 @@ var generateBook = require('./generateBook');
 function generateMock(Generator, files) {
     var fs = createMockFS(files);
     var book = Book.createForFS(fs);
-    var dir = tmp.dirSync();
+    var dir;
+
+    try {
+        dir = tmp.dirSync();
+    } catch(err) {
+        throw err;
+    }
 
     book = book.setLogLevel('disabled');
 

lib/output/generatePage.js

@@ -4,7 +4,6 @@ var Promise = require('../utils/promise');
 var error = require('../utils/error');
 var timing = require('../utils/timing');
 
-var Parse = require('../parse');
 var Templating = require('../templating');
 var JSONUtils = require('../json');
 var createTemplateEngine = require('./createTemplateEngine');

lib/output/getModifiers.js

@@ -4,22 +4,27 @@ var Api = require('../api');
 var Plugins = require('../plugins');
 var Promise = require('../utils/promise');
 var defaultBlocks = require('../constants/defaultBlocks');
+var fileToOutput = require('./helper/fileToOutput');
 
 var CODEBLOCK = 'code';
 
 /**
-    Return default modifier to prepare a page for
-    rendering.
-
-    @return {Array<Modifier>}
-*/
+ * Return default modifier to prepare a page for
+ * rendering.
+ *
+ * @return {Array<Modifier>}
+ */
 function getModifiers(output, page) {
     var book = output.getBook();
     var plugins = output.getPlugins();
     var glossary = book.getGlossary();
-    var entries = glossary.getEntries();
     var file = page.getFile();
 
+    // Glossary entries
+    var entries = glossary.getEntries();
+    var glossaryFile = glossary.getFile();
+    var glossaryFilename = fileToOutput(output, glossaryFile.getPath());
+
     // Current file path
     var currentFilePath = file.getPath();
 
@@ -34,18 +39,18 @@ function getModifiers(output, page) {
         // Normalize IDs on headings
         Modifiers.addHeadingId,
 
+        // Annotate text with glossary entries
+        Modifiers.annotateText.bind(null, entries, glossaryFilename),
+
+        // Resolve images
+        Modifiers.resolveImages.bind(null, currentFilePath),
+
         // Resolve links (.md -> .html)
         Modifiers.resolveLinks.bind(null,
             currentFilePath,
             resolveFileToURL.bind(null, output)
         ),
 
-        // Resolve images
-        Modifiers.resolveImages.bind(null, currentFilePath),
-
-        // Annotate text with glossary entries
-        Modifiers.annotateText.bind(null, entries),
-
         // Highlight code blocks using "code" block
         Modifiers.highlightCode.bind(null, function(lang, source) {
             return Promise(code.applyBlock({

lib/output/helper/fileToOutput.js

@@ -6,12 +6,12 @@ var LocationUtils = require('../../utils/location');
 var OUTPUT_EXTENSION = '.html';
 
 /**
-    Convert a filePath (absolute) to a filename for output
-
-    @param {Output} output
-    @param {String} filePath
-    @return {String}
-*/
+ * Convert a filePath (absolute) to a filename for output
+ *
+ * @param {Output} output
+ * @param {String} filePath
+ * @return {String}
+ */
 function fileToOutput(output, filePath) {
     var book = output.getBook();
     var readme = book.getReadme();

lib/output/helper/resolveFileToURL.js

@@ -3,12 +3,12 @@ var LocationUtils = require('../../utils/location');
 var fileToURL = require('./fileToURL');
 
 /**
-    Resolve an absolute path (extracted from a link)
-
-    @param {Output} output
-    @param {String} filePath
-    @return {String}
-*/
+ * Resolve an absolute path (extracted from a link)
+ *
+ * @param {Output} output
+ * @param {String} filePath
+ * @return {String}
+ */
 function resolveFileToURL(output, filePath) {
     // Convert /test.png -> test.png
     filePath = LocationUtils.toAbsolute(filePath, '', '');

lib/output/modifiers/__tests__/annotateText.js

@@ -12,7 +12,7 @@ describe('annotateText', function() {
     it('should annotate text', function() {
         var $ = cheerio.load('<p>This is a word, and multiple words</p>');
 
-        annotateText(entries, $);
+        annotateText(entries, 'GLOSSARY.md', $);
 
         var links = $('a');
         expect(links.length).toBe(2);
@@ -31,14 +31,14 @@ describe('annotateText', function() {
     it('should not annotate scripts', function() {
         var $ = cheerio.load('<script>This is a word, and multiple words</script>');
 
-        annotateText(entries, $);
+        annotateText(entries, 'GLOSSARY.md', $);
         expect($('a').length).toBe(0);
     });
 
     it('should not annotate when has class "no-glossary"', function() {
         var $ = cheerio.load('<p class="no-glossary">This is a word, and multiple words</p>');
 
-        annotateText(entries, $);
+        annotateText(entries, 'GLOSSARY.md', $);
         expect($('a').length).toBe(0);
     });
 });

lib/output/modifiers/__tests__/resolveLinks.js

@@ -4,7 +4,7 @@ var resolveLinks = require('../resolveLinks');
 
 describe('resolveLinks', function() {
     function resolveFileBasic(href) {
-        return href;
+        return 'fakeDir/' + href;
     }
 
     function resolveFileCustom(href) {
@@ -24,7 +24,7 @@ describe('resolveLinks', function() {
             return resolveLinks('hello.md', resolveFileBasic, $)
             .then(function() {
                 var link = $('a');
-                expect(link.attr('href')).toBe('test/cool.md');
+                expect(link.attr('href')).toBe('fakeDir/test/cool.md');
             });
         });
 
@@ -34,7 +34,31 @@ describe('resolveLinks', function() {
             return resolveLinks('afolder/hello.md', resolveFileBasic, $)
             .then(function() {
                 var link = $('a');
-                expect(link.attr('href')).toBe('../test/cool.md');
+                expect(link.attr('href')).toBe('../fakeDir/test/cool.md');
+            });
+        });
+    });
+
+    describe('Anchor', function() {
+        it('should prevent anchors in resolution', function() {
+            var TEST = '<p>This is a <a href="test/cool.md#an-anchor"></a></p>';
+            var $ = cheerio.load(TEST);
+
+            return resolveLinks('hello.md', resolveFileCustom, $)
+            .then(function() {
+                var link = $('a');
+                expect(link.attr('href')).toBe('test/cool.html#an-anchor');
+            });
+        });
+
+        it('should ignore pure anchor links', function() {
+            var TEST = '<p>This is a <a href="#an-anchor"></a></p>';
+            var $ = cheerio.load(TEST);
+
+            return resolveLinks('hello.md', resolveFileCustom, $)
+            .then(function() {
+                var link = $('a');
+                expect(link.attr('href')).toBe('#an-anchor');
             });
         });
     });
@@ -63,6 +87,18 @@ describe('resolveLinks', function() {
         });
     });
 
+    describe('External link', function() {
+        var TEST = '<p>This is a <a href="http://www.github.com">external link</a></p>';
+
+        it('should have target="_blank" attribute', function() {
+            var $ = cheerio.load(TEST);
+
+            return resolveLinks('hello.md', resolveFileBasic, $)
+            .then(function() {
+                var link = $('a');
+                expect(link.attr('target')).toBe('_blank');
+            });
+        });
+    });
+
 });
-
-

lib/output/modifiers/annotateText.js

@@ -59,18 +59,18 @@ function replaceText($, el, search, replace, text_only ) {
 }
 
 /**
-    Annotate text using a list of GlossaryEntry
-
-    @param {List<GlossaryEntry>}
-    @param {HTMLDom} $
-*/
-function annotateText(entries, $) {
+ * Annotate text using a list of GlossaryEntry
+ *
+ * @param {List<GlossaryEntry>}
+ * @param {String} glossaryFilePath
+ * @param {HTMLDom} $
+ */
+function annotateText(entries, glossaryFilePath, $) {
     entries.forEach(function(entry) {
-        var entryId = entry.getID();
-        var name = entry.getName();
+        var entryId     = entry.getID();
+        var name        = entry.getName();
         var description = entry.getDescription();
-
-        var searchRegex =  new RegExp( '\\b(' + pregQuote(name.toLowerCase()) + ')\\b' , 'gi' );
+        var searchRegex = new RegExp( '\\b(' + pregQuote(name.toLowerCase()) + ')\\b' , 'gi' );
 
         $('*').each(function() {
             var $this = $(this);
@@ -81,7 +81,7 @@ function annotateText(entries, $) {
             ) return;
 
             replaceText($, this, searchRegex, function(match) {
-                return '<a href="/GLOSSARY.md#' + entryId + '" '
+                return '<a href="/' + glossaryFilePath + '#' + entryId + '" '
                     + 'class="glossary-term" title="' + escape(description) + '">'
                     + match
                     + '</a>';

lib/output/modifiers/resolveLinks.js

@@ -1,4 +1,5 @@
 var path = require('path');
+var url = require('url');
 
 var LocationUtils = require('../../utils/location');
 var editHTMLElement = require('./editHTMLElement');
@@ -23,18 +24,27 @@ function resolveLinks(currentFile, resolveFile, $) {
         }
 
         if (LocationUtils.isExternal(href)) {
-            $a.attr('_target', 'blank');
+            $a.attr('target', '_blank');
             return;
         }
 
-        // Calcul absolute path for this
-        href = LocationUtils.toAbsolute(href, currentDirectory, '.');
+        // Split anchor
+        var parsed = url.parse(href);
+        href = parsed.pathname || '';
 
-        // Resolve file
-        href = resolveFile(href);
+        if (href) {
+            // Calcul absolute path for this
+            href = LocationUtils.toAbsolute(href, currentDirectory, '.');
 
-        // Convert back to relative
-        href = LocationUtils.relative(currentDirectory, href);
+            // Resolve file
+            href = resolveFile(href);
+
+            // Convert back to relative
+            href = LocationUtils.relative(currentDirectory, href);
+        }
+
+        // Add back anchor
+        href = href + (parsed.hash || '');
 
         $a.attr('href', href);
     });

lib/parse/__tests__/parsePageFromString.js

@@ -0,0 +1,37 @@
+var parsePageFromString = require('../parsePageFromString');
+var Page = require('../../models/page');
+
+describe('parsePageFromString', function() {
+    var page = new Page();
+
+    it('should parse YAML frontmatter', function() {
+        var CONTENT = '---\nhello: true\nworld: "cool"\n---\n# Hello World\n';
+        var newPage = parsePageFromString(page, CONTENT);
+
+        expect(newPage.getDir()).toBe('ltr');
+        expect(newPage.getContent()).toBe('# Hello World\n');
+
+        var attrs = newPage.getAttributes();
+        expect(attrs.size).toBe(2);
+        expect(attrs.get('hello')).toBe(true);
+        expect(attrs.get('world')).toBe('cool');
+    });
+
+    it('should parse text direction (english)', function() {
+        var CONTENT = 'Hello World';
+        var newPage = parsePageFromString(page, CONTENT);
+
+        expect(newPage.getDir()).toBe('ltr');
+        expect(newPage.getContent()).toBe('Hello World');
+        expect(newPage.getAttributes().size).toBe(0);
+    });
+
+    it('should parse text direction (arab)', function() {
+        var CONTENT = 'مرحبا بالعالم';
+        var newPage = parsePageFromString(page, CONTENT);
+
+        expect(newPage.getDir()).toBe('rtl');
+        expect(newPage.getContent()).toBe('مرحبا بالعالم');
+        expect(newPage.getAttributes().size).toBe(0);
+    });
+});

lib/parse/findParsableFile.js

@@ -8,7 +8,7 @@ var parsers = require('../parsers');
 
     @param {Book} book
     @param {String} filename
-    @return {Promise<>}
+    @return {Promise<File | Undefined>}
 */
 function findParsableFile(book, filename) {
     var fs = book.getContentFS();

lib/parse/index.js

@@ -1,13 +1,15 @@
 
 module.exports = {
-    parseBook:          require('./parseBook'),
-    parseSummary:       require('./parseSummary'),
-    parseGlossary:      require('./parseGlossary'),
-    parseReadme:        require('./parseReadme'),
-    parseConfig:        require('./parseConfig'),
-    parsePagesList:     require('./parsePagesList'),
-    parseIgnore:        require('./parseIgnore'),
-    listAssets:         require('./listAssets'),
-    parseLanguages:     require('./parseLanguages'),
-    parsePage:          require('./parsePage')
+    parseBook:           require('./parseBook'),
+    parseSummary:        require('./parseSummary'),
+    parseGlossary:       require('./parseGlossary'),
+    parseReadme:         require('./parseReadme'),
+    parseConfig:         require('./parseConfig'),
+    parsePagesList:      require('./parsePagesList'),
+    parseIgnore:         require('./parseIgnore'),
+    listAssets:          require('./listAssets'),
+    parseLanguages:      require('./parseLanguages'),
+    parsePage:           require('./parsePage'),
+    parsePageFromString: require('./parsePageFromString'),
+    lookupStructureFile: require('./lookupStructureFile')
 };

lib/parse/lookupStructureFile.js

@@ -0,0 +1,20 @@
+var findParsableFile = require('./findParsableFile');
+
+/**
+    Lookup a structure file (ex: SUMMARY.md, GLOSSARY.md) in a book. Uses
+    book's config to find it.
+
+    @param {Book} book
+    @param {String} type: one of ["glossary", "readme", "summary", "langs"]
+    @return {Promise<File | Undefined>} The path of the file found, relative
+    to the book content root.
+*/
+function lookupStructureFile(book, type) {
+    var config = book.getConfig();
+
+    var fileToSearch = config.getValue(['structure', type]);
+
+    return findParsableFile(book, fileToSearch);
+}
+
+module.exports = lookupStructureFile;

lib/parse/parseIgnore.js

@@ -1,6 +1,23 @@
 var Promise = require('../utils/promise');
 var IGNORE_FILES = require('../constants/ignoreFiles');
 
+var DEFAULT_IGNORES = [
+    // Skip Git stuff
+    '.git/',
+
+    // Skip OS X meta data
+    '.DS_Store',
+
+    // Skip stuff installed by plugins
+    'node_modules',
+
+    // Skip book outputs
+    '_book',
+
+    // Ignore files in the templates folder
+    '_layouts'
+];
+
 /**
     Parse ignore files
 
@@ -15,22 +32,7 @@ function parseIgnore(book) {
     var fs = book.getFS();
     var ignore = book.getIgnore();
 
-    ignore = ignore.add([
-        // Skip Git stuff
-        '.git/',
-
-        // Skip OS X meta data
-        '.DS_Store',
-
-        // Skip stuff installed by plugins
-        'node_modules',
-
-        // Skip book outputs
-        '_book',
-
-        // Ignore files in the templates folder
-        '_layouts'
-    ]);
+    ignore = ignore.add(DEFAULT_IGNORES);
 
     return Promise.serie(IGNORE_FILES, function(filename) {
         return fs.readAsString(filename)

lib/parse/parsePage.js

@@ -1,27 +1,19 @@
-var Immutable = require('immutable');
-var fm = require('front-matter');
-var direction = require('direction');
+var parsePageFromString = require('./parsePageFromString');
 
 /**
-    Parse a page, read its content and parse the YAMl header
-
-    @param {Book} book
-    @param {Page} page
-    @return {Promise<Page>}
-*/
+ * Parse a page, read its content and parse the YAMl header
+ *
+ * @param {Book} book
+ * @param {Page} page
+ * @return {Promise<Page>}
+ */
 function parsePage(book, page) {
     var fs = book.getContentFS();
     var file = page.getFile();
 
     return fs.readAsString(file.getPath())
     .then(function(content) {
-        var parsed = fm(content);
-
-        return page.merge({
-            content: parsed.body,
-            attributes: Immutable.fromJS(parsed.attributes),
-            dir: direction(parsed.body)
-        });
+        return parsePageFromString(page, content);
     });
 }
 

lib/parse/parsePageFromString.js

@@ -0,0 +1,22 @@
+var Immutable = require('immutable');
+var fm = require('front-matter');
+var direction = require('direction');
+
+/**
+ * Parse a page, its content and the YAMl header
+ *
+ * @param {Page} page
+ * @return {Page}
+ */
+function parsePageFromString(page, content) {
+    var parsed = fm(content);
+
+    return page.merge({
+        content:    parsed.body,
+        attributes: Immutable.fromJS(parsed.attributes),
+        dir:        direction(parsed.body)
+    });
+}
+
+
+module.exports = parsePageFromString;

lib/parse/parsePagesList.js

@@ -5,6 +5,25 @@ var Page = require('../models/page');
 var walkSummary = require('./walkSummary');
 var parsePage = require('./parsePage');
 
+
+/**
+    Parse a page from a path
+
+    @param {Book} book
+    @param {String} filePath
+    @return {Page}
+*/
+function parseFilePage(book, filePath) {
+    var fs = book.getContentFS();
+
+    return fs.statFile(filePath)
+    .then(function(file) {
+        var page = Page.createForFile(file);
+        return parsePage(book, page);
+    });
+}
+
+
 /**
     Parse all pages from a book as an OrderedMap
 
@@ -12,10 +31,11 @@ var parsePage = require('./parsePage');
     @return {Promise<OrderedMap<Page>>}
 */
 function parsePagesList(book) {
-    var fs = book.getContentFS();
     var summary = book.getSummary();
+    var glossary = book.getGlossary();
     var map = Immutable.OrderedMap();
 
+    // Parse pages from summary
     return timing.measure(
         'parse.listPages',
         walkSummary(summary, function(article) {
@@ -26,21 +46,32 @@ function parsePagesList(book) {
             // Is the page ignored?
             if (book.isContentFileIgnored(filepath)) return;
 
-            return fs.statFile(filepath)
-            .then(function(file) {
-                var page = Page.createForFile(file);
-                return parsePage(book, page);
-            })
+            return parseFilePage(book, filepath)
             .then(function(page) {
                 map = map.set(filepath, page);
             }, function() {
                 // file doesn't exist
             });
         })
-        .then(function() {
-            return map;
-        })
-    );
+    )
+
+    // Parse glossary
+    .then(function() {
+        var file = glossary.getFile();
+
+        if (!file.exists()) {
+            return;
+        }
+
+        return parseFilePage(book, file.getPath())
+        .then(function(page) {
+            map = map.set(file.getPath(), page);
+        });
+    })
+
+    .then(function() {
+        return map;
+    });
 }
 
 

lib/parse/parseStructureFile.js

@@ -1,6 +1,6 @@
-var findParsableFile = require('./findParsableFile');
 var Promise = require('../utils/promise');
 var error = require('../utils/error');
+var lookupStructureFile = require('./lookupStructureFile');
 
 /**
     Parse a ParsableFile using a specific method
@@ -55,11 +55,8 @@ function parseFile(fs, file, type) {
 */
 function parseStructureFile(book, type) {
     var fs = book.getContentFS();
-    var config = book.getConfig();
 
-    var fileToSearch = config.getValue(['structure', type]);
-
-    return findParsableFile(book, fileToSearch)
+    return lookupStructureFile(book, type)
     .then(function(file) {
         if (!file) return [undefined, undefined];
 

lib/parse/parseSummary.js

@@ -1,7 +1,6 @@
 var parseStructureFile = require('./parseStructureFile');
 var Summary = require('../models/summary');
 var SummaryModifier = require('../modifiers').Summary;
-var location = require('../utils/location');
 
 /**
     Parse summary in a book, the summary can only be parsed
@@ -27,11 +26,10 @@ function parseSummary(book) {
             summary = Summary.createFromParts(file, result.parts);
         }
 
-        // Insert readme as first entry
-        var firstArticle = summary.getFirstArticle();
+        // Insert readme as first entry if not in SUMMARY.md
+        var readmeArticle = summary.getByPath(readmeFile.getPath());
 
-        if (readmeFile.exists() &&
-            (!firstArticle || !location.areIdenticalPaths(firstArticle.getRef(), readmeFile.getPath()))) {
+        if (readmeFile.exists() && !readmeArticle) {
             summary = SummaryModifier.unshiftArticle(summary, {
                 title: 'Introduction',
                 ref: readmeFile.getPath()

lib/parse/validateConfig.js

@@ -1,9 +1,9 @@
 var jsonschema = require('jsonschema');
 var jsonSchemaDefaults = require('json-schema-defaults');
-var mergeDefaults = require('merge-defaults');
 
 var schema = require('../constants/configSchema');
 var error = require('../utils/error');
+var mergeDefaults = require('../utils/mergeDefaults');
 
 /**
     Validate a book.json content

lib/parsers.js

@@ -4,20 +4,22 @@ var Immutable = require('immutable');
 var markdownParser = require('gitbook-markdown');
 var asciidocParser = require('gitbook-asciidoc');
 
+var EXTENSIONS_MARKDOWN = require('./constants/extsMarkdown');
+var EXTENSIONS_ASCIIDOC = require('./constants/extsAsciidoc');
 var Parser = require('./models/parser');
 
 // This list is ordered by priority of parsers to use
 var parsers = Immutable.List([
-    Parser.create('markdown', ['.md', '.markdown', '.mdown'], markdownParser),
-    Parser.create('asciidoc', ['.adoc', '.asciidoc'], asciidocParser)
+    Parser.create('markdown', EXTENSIONS_MARKDOWN, markdownParser),
+    Parser.create('asciidoc', EXTENSIONS_ASCIIDOC, asciidocParser)
 ]);
 
 /**
-    Return a specific parser by its name
-
-    @param {String} name
-    @return {Parser|undefined}
-*/
+ * Return a specific parser by its name
+ *
+ * @param {String} name
+ * @return {Parser|undefined}
+ */
 function getParser(name) {
     return parsers.find(function(parser) {
         return parser.getName() === name;
@@ -25,11 +27,11 @@ function getParser(name) {
 }
 
 /**
-    Return a specific parser according to an extension
-
-    @param {String} ext
-    @return {Parser|undefined}
-*/
+ * Return a specific parser according to an extension
+ *
+ * @param {String} ext
+ * @return {Parser|undefined}
+ */
 function getParserByExt(ext) {
     return parsers.find(function(parser) {
         return parser.matchExtension(ext);
@@ -37,11 +39,11 @@ function getParserByExt(ext) {
 }
 
 /**
-    Return parser for a file
-
-    @param {String} ext
-    @return {Parser|undefined}
-*/
+ * Return parser for a file
+ *
+ * @param {String} ext
+ * @return {Parser|undefined}
+ */
 function getParserForFile(filename) {
     return getParserByExt(path.extname(filename));
 }

lib/plugins/__tests__/findForBook.js

@@ -0,0 +1,19 @@
+var path = require('path');
+
+var Book = require('../../models/book');
+var createNodeFS = require('../../fs/node');
+var findForBook = require('../findForBook');
+
+describe('findForBook', function() {
+    var fs = createNodeFS(
+        path.resolve(__dirname, '../../..')
+    );
+    var book = Book.createForFS(fs);
+
+    it('should list default plugins', function() {
+        return findForBook(book)
+        .then(function(plugins) {
+            expect(plugins.has('fontsettings')).toBeTruthy();
+        });
+    });
+});

lib/plugins/__tests__/installPlugin.js

@@ -0,0 +1,29 @@
+var path = require('path');
+
+var PluginDependency = require('../../models/pluginDependency');
+var Book = require('../../models/book');
+var NodeFS = require('../../fs/node');
+var installPlugin = require('../installPlugin');
+
+var Parse = require('../../parse');
+
+describe('installPlugin', function() {
+    var book;
+
+    this.timeout(30000);
+
+    before(function() {
+        var fs = NodeFS(path.resolve(__dirname, '../../../'));
+        var baseBook = Book.createForFS(fs);
+
+        return Parse.parseConfig(baseBook)
+        .then(function(_book) {
+            book = _book;
+        });
+    });
+
+    it('must install a plugin from NPM', function() {
+        var dep = PluginDependency.createFromString('ga');
+        return installPlugin(book, dep);
+    });
+});

lib/plugins/__tests__/installPlugins.js

@@ -0,0 +1,30 @@
+var path = require('path');
+
+var Book = require('../../models/book');
+var NodeFS = require('../../fs/node');
+var installPlugins = require('../installPlugins');
+
+var Parse = require('../../parse');
+
+describe('installPlugins', function() {
+    var book;
+
+    this.timeout(30000);
+
+    before(function() {
+        var fs = NodeFS(path.resolve(__dirname, '../../../'));
+        var baseBook = Book.createForFS(fs);
+
+        return Parse.parseConfig(baseBook)
+        .then(function(_book) {
+            book = _book;
+        });
+    });
+
+    it('must install all plugins from NPM', function() {
+        return installPlugins(book)
+        .then(function(n) {
+            expect(n).toBe(2);
+        });
+    });
+});

lib/plugins/__tests__/listAll.js

@@ -1,36 +0,0 @@
-var PluginDependency = require('../../models/pluginDependency');
-var listAll = require('../listAll');
-
-describe('listAll', function() {
-    it('must list default', function() {
-        var deps = PluginDependency.listFromString('ga,great');
-        var plugins = listAll(deps);
-
-        expect(plugins.size).toBe(8);
-
-        expect(plugins.has('ga')).toBe(true);
-        expect(plugins.has('great')).toBe(true);
-
-        expect(plugins.has('search')).toBe(true);
-    });
-
-    it('must list from array with -', function() {
-        var deps = PluginDependency.listFromString('ga,-great');
-        var plugins = listAll(deps);
-
-        expect(plugins.size).toBe(7);
-
-        expect(plugins.has('ga')).toBe(true);
-        expect(plugins.has('great')).toBe(false);
-    });
-
-    it('must remove default plugins using -', function() {
-        var deps = PluginDependency.listFromString('ga,-search');
-        var plugins = listAll(deps);
-
-        expect(plugins.size).toBe(6);
-
-        expect(plugins.has('ga')).toBe(true);
-        expect(plugins.has('search')).toBe(false);
-    });
-});

lib/plugins/__tests__/listDependencies.js

@@ -0,0 +1,38 @@
+var PluginDependency = require('../../models/pluginDependency');
+var listDependencies = require('../listDependencies');
+var toNames = require('../toNames');
+
+describe('listDependencies', function() {
+    it('must list default', function() {
+        var deps = PluginDependency.listFromString('ga,great');
+        var plugins = listDependencies(deps);
+        var names = toNames(plugins);
+
+        expect(names).toEqual([
+            'ga', 'great',
+            'highlight', 'search', 'lunr', 'sharing', 'fontsettings',
+            'theme-default' ]);
+    });
+
+    it('must list from array with -', function() {
+        var deps = PluginDependency.listFromString('ga,-great');
+        var plugins = listDependencies(deps);
+        var names = toNames(plugins);
+
+        expect(names).toEqual([
+            'ga',
+            'highlight', 'search', 'lunr', 'sharing', 'fontsettings',
+            'theme-default' ]);
+    });
+
+    it('must remove default plugins using -', function() {
+        var deps = PluginDependency.listFromString('ga,-search');
+        var plugins = listDependencies(deps);
+        var names = toNames(plugins);
+
+        expect(names).toEqual([
+            'ga',
+            'highlight', 'lunr', 'sharing', 'fontsettings',
+            'theme-default' ]);
+    });
+});

lib/plugins/__tests__/locateRootFolder.js

@@ -0,0 +1,10 @@
+var path = require('path');
+var locateRootFolder = require('../locateRootFolder');
+
+describe('locateRootFolder', function() {
+    it('should correctly resolve the node_modules for gitbook', function() {
+        expect(locateRootFolder()).toBe(
+            path.resolve(__dirname, '../../../')
+        );
+    });
+});

lib/plugins/__tests__/resolveVersion.js

@@ -0,0 +1,22 @@
+var PluginDependency = require('../../models/pluginDependency');
+var resolveVersion = require('../resolveVersion');
+
+describe('resolveVersion', function() {
+    it('must skip resolving and return non-semver versions', function() {
+        var plugin = PluginDependency.createFromString('ga@git+ssh://samy@github.com/GitbookIO/plugin-ga.git');
+
+        return resolveVersion(plugin)
+        .then(function(version) {
+            expect(version).toBe('git+ssh://samy@github.com/GitbookIO/plugin-ga.git');
+        });
+    });
+
+    it('must resolve a normal plugin dependency', function() {
+        var plugin = PluginDependency.createFromString('ga@>0.9.0 < 1.0.1');
+
+        return resolveVersion(plugin)
+        .then(function(version) {
+            expect(version).toBe('1.0.0');
+        });
+    });
+});

lib/plugins/__tests__/sortDependencies.js

@@ -0,0 +1,42 @@
+var PluginDependency = require('../../models/pluginDependency');
+var sortDependencies = require('../sortDependencies');
+var toNames = require('../toNames');
+
+describe('sortDependencies', function() {
+    it('must load themes after plugins', function() {
+        var allPlugins = PluginDependency.listFromArray([
+            'hello',
+            'theme-test',
+            'world'
+        ]);
+
+        var sorted = sortDependencies(allPlugins);
+        var names = toNames(sorted);
+
+        expect(names).toEqual([
+            'hello',
+            'world',
+            'theme-test'
+        ]);
+    });
+
+    it('must keep order of themes', function() {
+        var allPlugins = PluginDependency.listFromArray([
+            'theme-test',
+            'theme-test1',
+            'hello',
+            'theme-test2',
+            'world'
+        ]);
+        var sorted = sortDependencies(allPlugins);
+        var names = toNames(sorted);
+
+        expect(names).toEqual([
+            'hello',
+            'world',
+            'theme-test',
+            'theme-test1',
+            'theme-test2'
+        ]);
+    });
+});

lib/plugins/findForBook.js

@@ -1,22 +1,22 @@
-var path = require('path');
 var Immutable = require('immutable');
 
 var Promise = require('../utils/promise');
 var timing = require('../utils/timing');
 var findInstalled = require('./findInstalled');
+var locateRootFolder = require('./locateRootFolder');
 
 /**
-    List all plugins installed in a book
-
-    @param {Book}
-    @return {Promise<OrderedMap<String:Plugin>>}
-*/
+ * List all plugins installed in a book
+ *
+ * @param {Book}
+ * @return {Promise<OrderedMap<String:Plugin>>}
+ */
 function findForBook(book) {
     return timing.measure(
         'plugins.findForBook',
 
         Promise.all([
-            findInstalled(path.resolve(__dirname, '../..')),
+            findInstalled(locateRootFolder()),
             findInstalled(book.getRoot())
         ])
 

lib/plugins/findInstalled.js

@@ -8,21 +8,21 @@ var Plugin = require('../models/plugin');
 var PREFIX = require('../constants/pluginPrefix');
 
 /**
-    Validate if a package name is a GitBook plugin
-
-    @return {Boolean}
-*/
+ * Validate if a package name is a GitBook plugin
+ *
+ * @return {Boolean}
+ */
 function validateId(name) {
     return name && name.indexOf(PREFIX) === 0;
 }
 
 
 /**
-    List all packages installed inside a folder
-
-    @param {String} folder
-    @return {OrderedMap<String:Plugin>}
-*/
+ * List all packages installed inside a folder
+ *
+ * @param {String} folder
+ * @return {OrderedMap<String:Plugin>}
+ */
 function findInstalled(folder) {
     var options = {
         dev: false,
@@ -31,7 +31,7 @@ function findInstalled(folder) {
     };
     var results = Immutable.OrderedMap();
 
-    function onPackage(pkg, isRoot) {
+    function onPackage(pkg, parent) {
         if (!pkg.name) return;
 
         var name = pkg.name;
@@ -43,18 +43,19 @@ function findInstalled(folder) {
         var pluginName = name.slice(PREFIX.length);
 
         if (!validateId(name)){
-            if (!isRoot) return;
+            if (parent) return;
         } else {
             results = results.set(pluginName, Plugin({
                 name: pluginName,
                 version: version,
                 path: pkgPath,
-                depth: depth
+                depth: depth,
+                parent: parent
             }));
         }
 
         Immutable.Map(dependencies).forEach(function(dep) {
-            onPackage(dep);
+            onPackage(dep, pluginName);
         });
     }
 
@@ -77,7 +78,7 @@ function findInstalled(folder) {
             var module_folder = path.join(node_modules, module);
             return Promise.nfcall(readInstalled, module_folder, options)
             .then(function(data) {
-                onPackage(data, true);
+                onPackage(data);
             });
         });
     })

lib/plugins/installPlugin.js

@@ -0,0 +1,47 @@
+var npmi = require('npmi');
+
+var Promise = require('../utils/promise');
+var resolveVersion = require('./resolveVersion');
+
+/**
+    Install a plugin for a book
+
+    @param {Book}
+    @param {PluginDependency}
+    @return {Promise}
+*/
+function installPlugin(book, plugin) {
+    var logger = book.getLogger();
+
+    var installFolder = book.getRoot();
+    var name = plugin.getName();
+    var requirement = plugin.getVersion();
+
+    logger.info.ln('');
+    logger.info.ln('installing plugin "' + name + '"');
+
+    // Find a version to install
+    return resolveVersion(plugin)
+    .then(function(version) {
+        if (!version) {
+            throw new Error('Found no satisfactory version for plugin "' + name + '" with requirement "' + requirement + '"');
+        }
+
+        logger.info.ln('install plugin "' + name +'" (' + requirement + ') from NPM with version', version);
+        return Promise.nfcall(npmi, {
+            'name': plugin.getNpmID(),
+            'version': version,
+            'path': installFolder,
+            'npmLoad': {
+                'loglevel': 'silent',
+                'loaded': true,
+                'prefix': installFolder
+            }
+        });
+    })
+    .then(function() {
+        logger.info.ok('plugin "' + name + '" installed with success');
+    });
+}
+
+module.exports = installPlugin;

lib/plugins/installPlugins.js

@@ -1,134 +1,34 @@
-var npm = require('npm');
 var npmi = require('npmi');
-var semver = require('semver');
-var Immutable = require('immutable');
 
-var pkg = require('../../package.json');
 var DEFAULT_PLUGINS = require('../constants/defaultPlugins');
 var Promise = require('../utils/promise');
-var Plugin = require('../models/plugin');
-var gitbook = require('../gitbook');
-var listForBook = require('./listForBook');
-
-var npmIsReady;
-
-/**
-    Initialize and prepare NPM
-
-    @return {Promise}
-*/
-function initNPM() {
-    if (npmIsReady) return npmIsReady;
-
-    npmIsReady = Promise.nfcall(npm.load, {
-        silent: true,
-        loglevel: 'silent'
-    });
-
-    return npmIsReady;
-}
-
-
-
-/**
-    Resolve a plugin to a version
-
-    @param {Plugin}
-    @return {Promise<String>}
-*/
-function resolveVersion(plugin) {
-    var npmId = Plugin.nameToNpmID(plugin.getName());
-    var requiredVersion = plugin.getVersion();
-
-    return initNPM()
-    .then(function() {
-        return Promise.nfcall(npm.commands.view, [npmId + '@' + requiredVersion, 'engines'], true);
-    })
-    .then(function(versions) {
-        versions = Immutable.Map(versions).entrySeq();
-
-        var result = versions
-            .map(function(entry) {
-                return {
-                    version: entry[0],
-                    gitbook: (entry[1].engines || {}).gitbook
-                };
-            })
-            .filter(function(v) {
-                return v.gitbook && gitbook.satisfies(v.gitbook);
-            })
-            .sort(function(v1, v2) {
-                return semver.lt(v1.version, v2.version)? 1 : -1;
-            })
-            .get(0);
-
-        if (!result) {
-            return undefined;
-        } else {
-            return result.version;
-        }
-    });
-}
-
-
-/**
-    Install a plugin for a book
-
-    @param {Book}
-    @param {Plugin}
-    @return {Promise}
-*/
-function installPlugin(book, plugin) {
-    var logger = book.getLogger();
-
-    var installFolder = book.getRoot();
-    var name = plugin.getName();
-    var requirement = plugin.getVersion();
-
-    logger.info.ln('');
-    logger.info.ln('installing plugin "' + name + '"');
-
-    // Find a version to install
-    return resolveVersion(plugin)
-    .then(function(version) {
-        if (!version) {
-            throw new Error('Found no satisfactory version for plugin "' + name + '" with requirement "' + requirement + '"');
-        }
-
-        logger.info.ln('install plugin "' + name +'" (' + requirement + ') from NPM with version', version);
-        return Promise.nfcall(npmi, {
-            'name': plugin.getNpmID(),
-            'version': version,
-            'path': installFolder,
-            'npmLoad': {
-                'loglevel': 'silent',
-                'loaded': true,
-                'prefix': installFolder
-            }
-        });
-    })
-    .then(function() {
-        logger.info.ok('plugin "' + name + '" installed with success');
-    });
-}
-
+var installPlugin = require('./installPlugin');
 
 /**
     Install plugin requirements for a book
 
     @param {Book}
-    @return {Promise}
+    @return {Promise<Number>}
 */
 function installPlugins(book) {
     var logger = book.getLogger();
-    var plugins = listForBook(book);
+    var config = book.getConfig();
+    var plugins = config.getPluginDependencies();
 
     // Remove default plugins
     // (only if version is same as installed)
     plugins = plugins.filterNot(function(plugin) {
+        var dependency = DEFAULT_PLUGINS.find(function(dep) {
+            return dep.getName() === plugin.getName();
+        });
+
         return (
-            DEFAULT_PLUGINS.includes(plugin.getName()) &&
-            plugin.getVersion() === pkg.dependencies[plugin.getNpmID()]
+            // Disabled plugin
+            !plugin.isEnabled() ||
+
+            // Or default one installed in GitBook itself
+            (dependency &&
+            plugin.getVersion() === dependency.getVersion())
         );
     });
 
@@ -141,7 +41,8 @@ function installPlugins(book) {
 
     return Promise.forEach(plugins, function(plugin) {
         return installPlugin(book, plugin);
-    });
+    })
+    .thenResolve(plugins.size);
 }
 
 module.exports = installPlugins;

lib/plugins/listAll.js

@@ -1,50 +0,0 @@
-var Immutable = require('immutable');
-var Plugin = require('../models/plugin');
-
-var pkg = require('../../package.json');
-var DEFAULT_PLUGINS = require('../constants/defaultPlugins');
-
-/**
-    List all plugins for a book
-
-    @param {List<PluginDependency>} deps
-    @return {OrderedMap<Plugin>}
-*/
-function listAll(deps) {
-    // Extract list of plugins to disable (starting with -)
-    var toRemove = deps
-        .filter(function(plugin) {
-            return !plugin.isEnabled();
-        })
-        .map(function(plugin) {
-            return plugin.getName();
-        });
-
-    // Convert to an ordered map of Plugin
-    var plugins = deps
-        .map(function(dep) {
-            var plugin = Plugin.createFromDep(dep);
-
-            return [dep.getName(), plugin];
-        });
-    plugins = Immutable.OrderedMap(plugins);
-
-    // Append default plugins
-    DEFAULT_PLUGINS.forEach(function(pluginName) {
-        if (plugins.has(pluginName)) return;
-
-        plugins = plugins.set(pluginName, new Plugin({
-            name: pluginName,
-            version: pkg.dependencies[Plugin.nameToNpmID(pluginName)]
-        }));
-    });
-
-    // Remove plugins
-    plugins = plugins.filterNot(function(plugin, name) {
-        return toRemove.includes(name);
-    });
-
-    return plugins;
-}
-
-module.exports = listAll;

lib/plugins/listDependencies.js

@@ -0,0 +1,33 @@
+var DEFAULT_PLUGINS = require('../constants/defaultPlugins');
+var sortDependencies = require('./sortDependencies');
+
+/**
+ * List all dependencies for a book, including default plugins.
+ * It returns a concat with default plugins and remove disabled ones.
+ *
+ * @param {List<PluginDependency>} deps
+ * @return {List<PluginDependency>}
+ */
+function listDependencies(deps) {
+    // Extract list of plugins to disable (starting with -)
+    var toRemove = deps
+        .filter(function(plugin) {
+            return !plugin.isEnabled();
+        })
+        .map(function(plugin) {
+            return plugin.getName();
+        });
+
+    // Concat with default plugins
+    deps = deps.concat(DEFAULT_PLUGINS);
+
+    // Remove plugins
+    deps = deps.filterNot(function(plugin) {
+        return toRemove.includes(plugin.getName());
+    });
+
+    // Sort
+    return sortDependencies(deps);
+}
+
+module.exports = listDependencies;

lib/plugins/listDepsForBook.js

@@ -0,0 +1,18 @@
+var listDependencies = require('./listDependencies');
+
+/**
+ * List all plugin requirements for a book.
+ * It can be different from the final list of plugins,
+ * since plugins can have their own dependencies
+ *
+ * @param {Book}
+ * @return {List<PluginDependency>}
+ */
+function listDepsForBook(book) {
+    var config = book.getConfig();
+    var plugins = config.getPluginDependencies();
+
+    return listDependencies(plugins);
+}
+
+module.exports = listDepsForBook;

lib/plugins/listForBook.js

@@ -1,18 +0,0 @@
-var listAll = require('./listAll');
-
-/**
-    List all plugin requirements for a book.
-    It can be different from the final list of plugins,
-    since plugins can have their own dependencies
-
-    @param {Book}
-    @return {OrderedMap<Plugin>}
-*/
-function listForBook(book) {
-    var config = book.getConfig();
-    var plugins = config.getPluginDependencies();
-
-    return listAll(plugins);
-}
-
-module.exports = listForBook;

lib/plugins/loadForBook.js

@@ -1,53 +1,69 @@
-var Promise = require('../utils/promise');
+var Immutable = require('immutable');
 
-var listForBook = require('./listForBook');
+var Promise = require('../utils/promise');
+var listDepsForBook = require('./listDepsForBook');
 var findForBook = require('./findForBook');
 var loadPlugin = require('./loadPlugin');
 
 
 /**
-    Load a list of plugins in a book
-
-    @param {Book}
-    @return {Promise<Map<String:Plugin>}
-*/
+ * Load all plugins in a book
+ *
+ * @param {Book}
+ * @return {Promise<Map<String:Plugin>}
+ */
 function loadForBook(book) {
     var logger = book.getLogger();
-    var requirements = listForBook(book);
-    var requirementsKeys = requirements.keySeq().toList();
 
+    // List the dependencies
+    var requirements = listDepsForBook(book);
+
+    // List all plugins installed in the book
     return findForBook(book)
-    .then(function(installed) {
-        // Filter out plugins not listed of first level
-        // (aka pre-installed plugins)
-        installed = installed.filter(function(plugin) {
-            return (
-                plugin.getDepth() > 0 ||
-                requirements.has(plugin.getName())
-            );
-        });
+    .then(function(installedMap) {
+        var missing = [];
+        var plugins = requirements.reduce(function(result, dep) {
+            var name = dep.getName();
+            var installed = installedMap.get(name);
 
-        // Sort plugins to match list in book.json
-        installed = installed.sort(function(a, b){
-            return requirementsKeys.indexOf(a.getName()) < requirementsKeys.indexOf(b.getName()) ? -1 : 1;
-        });
+            if (installed) {
+                var deps = installedMap
+                    .filter(function(plugin) {
+                        return plugin.getParent() === name;
+                    })
+                    .toArray();
+
+                result = result.concat(deps);
+                result.push(installed);
+            } else {
+                missing.push(name);
+            }
+
+            return result;
+        }, []);
+
+        // Convert plugins list to a map
+        plugins = Immutable.List(plugins)
+            .map(function(plugin) {
+                return [
+                    plugin.getName(),
+                    plugin
+                ];
+            });
+        plugins = Immutable.OrderedMap(plugins);
 
         // Log state
-        logger.info.ln(installed.size + ' plugins are installed');
-        if (requirements.size != installed.size) {
+        logger.info.ln(installedMap.size + ' plugins are installed');
+        if (requirements.size != installedMap.size) {
             logger.info.ln(requirements.size + ' explicitly listed');
         }
 
         // Verify that all plugins are present
-        var notInstalled = requirementsKeys.filter(function(name) {
-            return !installed.has(name);
-        });
-
-        if (notInstalled.size > 0) {
-            throw new Error('Couldn\'t locate plugins "' + notInstalled.join(', ') + '", Run \'gitbook install\' to install plugins from registry.');
+        if (missing.length > 0) {
+            throw new Error('Couldn\'t locate plugins "' + missing.join(', ') + '", Run \'gitbook install\' to install plugins from registry.');
         }
 
-        return Promise.map(installed, function(plugin) {
+        return Promise.map(plugins, function(plugin) {
             return loadPlugin(book, plugin);
         });
     });

lib/plugins/locateRootFolder.js

@@ -0,0 +1,22 @@
+var path = require('path');
+var resolve = require('resolve');
+
+var DEFAULT_PLUGINS = require('../constants/defaultPlugins');
+
+/**
+ * Resolve the root folder containing for node_modules
+ * since gitbook can be used as a library and dependency can be flattened.
+ *
+ * @return {String} folderPath
+ */
+function locateRootFolder() {
+    var firstDefaultPlugin = DEFAULT_PLUGINS.first();
+    var pluginPath = resolve.sync(firstDefaultPlugin.getNpmID() + '/package.json', {
+        basedir: __dirname
+    });
+    var nodeModules = path.resolve(pluginPath, '../../..');
+
+    return nodeModules;
+}
+
+module.exports = locateRootFolder;

lib/plugins/resolveVersion.js

@@ -0,0 +1,71 @@
+var npm = require('npm');
+var semver = require('semver');
+var Immutable = require('immutable');
+
+var Promise = require('../utils/promise');
+var Plugin = require('../models/plugin');
+var gitbook = require('../gitbook');
+
+var npmIsReady;
+
+/**
+    Initialize and prepare NPM
+
+    @return {Promise}
+*/
+function initNPM() {
+    if (npmIsReady) return npmIsReady;
+
+    npmIsReady = Promise.nfcall(npm.load, {
+        silent: true,
+        loglevel: 'silent'
+    });
+
+    return npmIsReady;
+}
+
+/**
+    Resolve a plugin dependency to a version
+
+    @param {PluginDependency} plugin
+    @return {Promise<String>}
+*/
+function resolveVersion(plugin) {
+    var npmId = Plugin.nameToNpmID(plugin.getName());
+    var requiredVersion = plugin.getVersion();
+
+    if (plugin.isGitDependency()) {
+        return Promise.resolve(requiredVersion);
+    }
+
+    return initNPM()
+    .then(function() {
+        return Promise.nfcall(npm.commands.view, [npmId + '@' + requiredVersion, 'engines'], true);
+    })
+    .then(function(versions) {
+        versions = Immutable.Map(versions).entrySeq();
+
+        var result = versions
+            .map(function(entry) {
+                return {
+                    version: entry[0],
+                    gitbook: (entry[1].engines || {}).gitbook
+                };
+            })
+            .filter(function(v) {
+                return v.gitbook && gitbook.satisfies(v.gitbook);
+            })
+            .sort(function(v1, v2) {
+                return semver.lt(v1.version, v2.version)? 1 : -1;
+            })
+            .get(0);
+
+        if (!result) {
+            return undefined;
+        } else {
+            return result.version;
+        }
+    });
+}
+
+module.exports = resolveVersion;

lib/plugins/sortDependencies.js

@@ -0,0 +1,34 @@
+var Immutable = require('immutable');
+
+var THEME_PREFIX = require('../constants/themePrefix');
+
+var TYPE_PLUGIN = 'plugin';
+var TYPE_THEME  = 'theme';
+
+
+/**
+ * Returns the type of a plugin given its name
+ * @param {Plugin} plugin
+ * @return {String}
+ */
+function pluginType(plugin) {
+    var name = plugin.getName();
+    return (name && name.indexOf(THEME_PREFIX) === 0) ? TYPE_THEME : TYPE_PLUGIN;
+}
+
+
+/**
+ * Sort the list of dependencies to match list in book.json
+ * The themes should always be loaded after the plugins
+ *
+ * @param {List<PluginDependency>} deps
+ * @return {List<PluginDependency>}
+ */
+function sortDependencies(plugins) {
+    var byTypes = plugins.groupBy(pluginType);
+
+    return byTypes.get(TYPE_PLUGIN, Immutable.List())
+        .concat(byTypes.get(TYPE_THEME, Immutable.List()));
+}
+
+module.exports = sortDependencies;

lib/plugins/toNames.js

@@ -0,0 +1,16 @@
+
+/**
+ * Return list of plugin names. This method is nly used in unit tests.
+ *
+ * @param {OrderedMap<String:Plugin} plugins
+ * @return {Array<String>}
+ */
+function toNames(plugins) {
+    return plugins
+        .map(function(plugin) {
+            return plugin.getName();
+        })
+        .toArray();
+}
+
+module.exports = toNames;

lib/plugins/validateConfig.js

@@ -1,10 +1,10 @@
 var Immutable = require('immutable');
 var jsonschema = require('jsonschema');
 var jsonSchemaDefaults = require('json-schema-defaults');
-var mergeDefaults = require('merge-defaults');
 
 var Promise = require('../utils/promise');
 var error = require('../utils/error');
+var mergeDefaults = require('../utils/mergeDefaults');
 
 /**
     Validate one plugin for a book and update book's confiration

lib/templating/__tests__/conrefsLoader.js

@@ -75,6 +75,12 @@ describe('ConrefsLoader', function() {
 
     describe('transform', function() {
         function transform(filePath, source) {
+            expect(filePath).toBeA('string');
+            expect(source).toBeA('string');
+
+            expect(filePath).toBe(path.resolve(__dirname, 'include.md'));
+            expect(source).toBe('Hello World');
+
             return 'test-' + source + '-endtest';
         }
         var engine = TemplateEngine({

lib/templating/__tests__/postRender.js

@@ -0,0 +1,51 @@
+var TemplateEngine = require('../../models/templateEngine');
+var TemplateBlock = require('../../models/templateBlock');
+
+var renderTemplate = require('../render');
+var postRender = require('../postRender');
+
+describe('postRender', function() {
+    var testPost;
+    var engine = TemplateEngine.create({
+        blocks: [
+            TemplateBlock.create('lower', function(blk) {
+                return blk.body.toLowerCase();
+            }),
+            TemplateBlock.create('prefix', function(blk) {
+                return {
+                    body: '_' + blk.body + '_',
+                    post: function() {
+                        testPost = true;
+                    }
+                };
+            })
+        ]
+    });
+
+    it('should correctly replace block', function() {
+        return renderTemplate(engine, 'README.md', 'Hello {% lower %}Samy{% endlower %}')
+        .then(function(output) {
+            expect(output.getContent()).toMatch(/Hello \{\{\-([\S]+)\-\}\}/);
+            expect(output.getBlocks().size).toBe(1);
+
+            return postRender(engine, output);
+        })
+        .then(function(result) {
+            expect(result).toBe('Hello samy');
+        });
+    });
+
+    it('should correctly replace blocks', function() {
+        return renderTemplate(engine, 'README.md', 'Hello {% lower %}Samy{% endlower %}{% prefix %}Pesse{% endprefix %}')
+        .then(function(output) {
+            expect(output.getContent()).toMatch(/Hello \{\{\-([\S]+)\-\}\}\{\{\-([\S]+)\-\}\}/);
+            expect(output.getBlocks().size).toBe(2);
+            return postRender(engine, output);
+        })
+        .then(function(result) {
+            expect(result).toBe('Hello samy_Pesse_');
+            expect(testPost).toBe(true);
+        });
+    });
+
+});

lib/templating/conrefsLoader.js

@@ -8,16 +8,15 @@ var PathUtils = require('../utils/path');
 
 
 /**
-    Template loader resolving both:
-        - relative url ("./test.md")
-        - absolute url ("/test.md")
-        - git url ("")
-
-
-    @param {String} rootFolder
-    @param {Function(filePath, source)} transformFn (optional)
-    @param {Logger} logger (optional)
-*/
+ * Template loader resolving both:
+ *      - relative url ("./test.md")
+ *      - absolute url ("/test.md")
+ *      - git url ("")
+ *
+ * @param {String} rootFolder
+ * @param {Function(filePath, source)} transformFn (optional)
+ * @param {Logger} logger (optional)
+ */
 var ConrefsLoader = nunjucks.Loader.extend({
     async: true,
 
@@ -43,6 +42,8 @@ var ConrefsLoader = nunjucks.Loader.extend({
             // Read file from absolute path
             return fs.readFile(filepath)
             .then(function(source) {
+                source = source.toString('utf8');
+
                 if (that.transformFn) {
                     return that.transformFn(filepath, source);
                 }
@@ -51,7 +52,7 @@ var ConrefsLoader = nunjucks.Loader.extend({
             })
             .then(function(source) {
                 return {
-                    src: source.toString('utf8'),
+                    src: source,
                     path: filepath
                 };
             });

lib/templating/listShortcuts.js

@@ -2,13 +2,13 @@ var Immutable = require('immutable');
 var parsers = require('../parsers');
 
 /**
-    Return a list of all shortcuts that can apply
-    to a file for a TemplatEngine
-
-    @param {List<TemplateBlock>} engine
-    @param {String} filePath
-    @return {List<TemplateShortcut>}
-*/
+ * Return a list of all shortcuts that can apply
+ * to a file for a TemplatEngine
+ *
+ * @param {List<TemplateBlock>} engine
+ * @param {String} filePath
+ * @return {List<TemplateShortcut>}
+ */
 function listShortcuts(blocks, filePath) {
     var parser = parsers.getForFile(filePath);
 

lib/templating/postRender.js

@@ -2,12 +2,12 @@ var Promise = require('../utils/promise');
 
 
 /**
-    Replace position markers of blocks by body after processing
-    This is done to avoid that markdown/asciidoc processer parse the block content
-
-    @param {String} content
-    @return {Object} {blocks: Set, content: String}
-*/
+ * Replace position markers of blocks by body after processing
+ * This is done to avoid that markdown/asciidoc processer parse the block content
+ *
+ * @param {String} content
+ * @return {Object} {blocks: Set, content: String}
+ */
 function replaceBlocks(content, blocks) {
     var newContent = content.replace(/\{\{\-\%([\s\S]+?)\%\-\}\}/g, function(match, key) {
         var replacedWith = match;
@@ -24,14 +24,14 @@ function replaceBlocks(content, blocks) {
 }
 
 /**
-    Post render a template:
-        - Execute "post" for blocks
-        - Replace block content
-
-    @param {TemplateEngine} engine
-    @param {TemplateOutput} content
-    @return {Promise<String>}
-*/
+ * Post render a template:
+ *     - Execute "post" for blocks
+ *     - Replace block content
+ *
+ * @param {TemplateEngine} engine
+ * @param {TemplateOutput} content
+ * @return {Promise<String>}
+ */
 function postRender(engine, output) {
     var content = output.getContent();
     var blocks = output.getBlocks();

lib/templating/render.js

@@ -4,14 +4,14 @@ var TemplateOutput = require('../models/templateOutput');
 var replaceShortcuts = require('./replaceShortcuts');
 
 /**
-    Render a template
-
-    @param {TemplateEngine} engine
-    @param {String} filePath: absolute path for the loader
-    @param {String} content
-    @param {Object} context
-    @return {Promise<TemplateOutput>}
-*/
+ * Render a template
+ *
+ * @param {TemplateEngine} engine
+ * @param {String} filePath: absolute path for the loader
+ * @param {String} content
+ * @param {Object} context (optional)
+ * @return {Promise<TemplateOutput>}
+ */
 function renderTemplate(engine, filePath, content, context) {
     context = context || {};
 

lib/templating/renderFile.js

@@ -3,13 +3,13 @@ var error = require('../utils/error');
 var render = require('./render');
 
 /**
-    Render a template
-
-    @param {TemplateEngine} engine
-    @param {String} filePath
-    @param {Object} context
-    @return {Promise<TemplateOutput>}
-*/
+ * Render a template
+ *
+ * @param {TemplateEngine} engine
+ * @param {String} filePath
+ * @param {Object} context
+ * @return {Promise<TemplateOutput>}
+ */
 function renderTemplateFile(engine, filePath, context) {
     var loader = engine.getLoader();
 

lib/templating/replaceShortcuts.js

@@ -1,12 +1,12 @@
 var escapeStringRegexp = require('escape-string-regexp');
 var listShortcuts = require('./listShortcuts');
 
-/*
-    Apply a shortcut of block to a template
-    @param {String} content
-    @param {Shortcut} shortcut
-    @return {String}
-*/
+/**
+ * Apply a shortcut of block to a template
+ * @param {String} content
+ * @param {Shortcut} shortcut
+ * @return {String}
+ */
 function applyShortcut(content, shortcut) {
     var start = shortcut.getStart();
     var end = shortcut.getEnd();
@@ -24,13 +24,13 @@ function applyShortcut(content, shortcut) {
 }
 
 /**
-    Replace shortcuts from blocks in a string
-
-    @param {List<TemplateBlock>} engine
-    @param {String} filePath
-    @param {String} content
-    @return {String}
-*/
+ * Replace shortcuts from blocks in a string
+ *
+ * @param {List<TemplateBlock>} engine
+ * @param {String} filePath
+ * @param {String} content
+ * @return {String}
+ */
 function replaceShortcuts(blocks, filePath, content) {
     var shortcuts = listShortcuts(blocks, filePath);
     return shortcuts.reduce(applyShortcut, content);

lib/templating/themesLoader.js

@@ -12,11 +12,11 @@ var ThemesLoader = nunjucks.Loader.extend({
             .map(path.normalize);
     },
 
-    /*
-        Read source of a resolved filepath
-        @param {String}
-        @return {Object}
-    */
+    /**
+     * Read source of a resolved filepath
+     * @param {String}
+     * @return {Object}
+     */
     getSource: function(fullpath) {
         if (!fullpath) return null;
 
@@ -40,19 +40,19 @@ var ThemesLoader = nunjucks.Loader.extend({
         };
     },
 
-    /*
-        Nunjucks calls "isRelative" to determine when to call "resolve".
-        We handle absolute paths ourselves in ".resolve" so we always return true
-    */
+    /**
+     * Nunjucks calls "isRelative" to determine when to call "resolve".
+     * We handle absolute paths ourselves in ".resolve" so we always return true
+     */
     isRelative: function() {
         return true;
     },
 
-    /*
-        Get original search path containing a template
-        @param {String} filepath
-        @return {String} searchPath
-    */
+    /**
+     * Get original search path containing a template
+     * @param {String} filepath
+     * @return {String} searchPath
+     */
     getSearchPath: function(filepath) {
         return this.searchPaths
             .sortBy(function(s) {
@@ -63,22 +63,22 @@ var ThemesLoader = nunjucks.Loader.extend({
             });
     },
 
-    /*
-        Get template name from a filepath
-        @param {String} filepath
-        @return {String} name
-    */
+    /**
+     * Get template name from a filepath
+     * @param {String} filepath
+     * @return {String} name
+     */
     getTemplateName: function(filepath) {
         var originalSearchPath = this.getSearchPath(filepath);
         return originalSearchPath? path.relative(originalSearchPath, filepath) : null;
     },
 
-    /*
-        Resolve a template from a current template
-        @param {String|null} from
-        @param {String} to
-        @return {String|null}
-    */
+    /**
+     * Resolve a template from a current template
+     * @param {String|null} from
+     * @param {String} to
+     * @return {String|null}
+     */
     resolve: function(from, to) {
         var searchPaths = this.searchPaths;
 

lib/utils/__tests__/location.js

@@ -39,6 +39,21 @@ describe('LocationUtils', function() {
         });
     });
 
+    describe('.flatten', function() {
+        it('should remove leading slash', function() {
+            expect(LocationUtils.flatten('/test.md')).toBe('test.md');
+            expect(LocationUtils.flatten('/hello/cool.md')).toBe('hello/cool.md');
+        });
+
+        it('should remove leading slashes', function() {
+            expect(LocationUtils.flatten('///test.md')).toBe('test.md');
+        });
+
+        it('should not break paths', function() {
+            expect(LocationUtils.flatten('hello/cool.md')).toBe('hello/cool.md');
+        });
+    });
+
     describe('.toAbsolute', function() {
         it('should correctly transform as absolute', function() {
             expect(LocationUtils.toAbsolute('http://google.fr')).toBe('http://google.fr');

lib/utils/location.js

@@ -40,13 +40,28 @@ function normalize(s) {
 }
 
 /**
-    Convert a relative path to absolute
+ * Flatten a path, it removes the leading "/"
+ *
+ * @param {String} href
+ * @return {String}
+ */
+function flatten(href) {
+    href = normalize(href);
+    if (href[0] == '/') {
+        href = normalize(href.slice(1));
+    }
 
-    @param {String} href
-    @param {String} dir: directory parent of the file currently in rendering process
-    @param {String} outdir: directory parent from the html output
-    @return {String}
-*/
+    return href;
+}
+
+/**
+ * Convert a relative path to absolute
+ *
+ * @param {String} href
+ * @param {String} dir: directory parent of the file currently in rendering process
+ * @param {String} outdir: directory parent from the html output
+ * @return {String}
+ */
 function toAbsolute(_href, dir, outdir) {
     if (isExternal(_href) || isDataURI(_href)) {
         return _href;
@@ -74,50 +89,51 @@ function toAbsolute(_href, dir, outdir) {
 }
 
 /**
-    Convert an absolute path to a relative path for a specific folder (dir)
-    ('test/', 'hello.md') -> '../hello.md'
-
-    @param {String} dir: current directory
-    @param {String} file: absolute path of file
-    @return {String}
-*/
+ * Convert an absolute path to a relative path for a specific folder (dir)
+ * ('test/', 'hello.md') -> '../hello.md'
+ *
+ * @param {String} dir: current directory
+ * @param {String} file: absolute path of file
+ * @return {String}
+ */
 function relative(dir, file) {
     var isDirectory = file.slice(-1) === '/';
     return normalize(path.relative(dir, file)) + (isDirectory? '/': '');
 }
 
 /**
-    Convert an absolute path to a relative path for a specific folder (dir)
-    ('test/test.md', 'hello.md') -> '../hello.md'
-
-    @param {String} baseFile: current file
-    @param {String} file: absolute path of file
-    @return {String}
-*/
+ * Convert an absolute path to a relative path for a specific folder (dir)
+ * ('test/test.md', 'hello.md') -> '../hello.md'
+ *
+ * @param {String} baseFile: current file
+ * @param {String} file: absolute path of file
+ * @return {String}
+ */
 function relativeForFile(baseFile, file) {
     return relative(path.dirname(baseFile), file);
 }
 
 /**
-    Compare two paths, return true if they are identical
-    ('README.md', './README.md') -> true
-
-    @param {String} p1: first path
-    @param {String} p2: second path
-    @return {Boolean}
-*/
+ * Compare two paths, return true if they are identical
+ * ('README.md', './README.md') -> true
+ *
+ * @param {String} p1: first path
+ * @param {String} p2: second path
+ * @return {Boolean}
+ */
 function areIdenticalPaths(p1, p2) {
     return normalize(p1) === normalize(p2);
 }
 
 module.exports = {
     areIdenticalPaths: areIdenticalPaths,
-    isDataURI: isDataURI,
-    isExternal: isExternal,
-    isRelative: isRelative,
-    isAnchor: isAnchor,
-    normalize: normalize,
-    toAbsolute: toAbsolute,
-    relative: relative,
-    relativeForFile: relativeForFile
+    isDataURI:         isDataURI,
+    isExternal:        isExternal,
+    isRelative:        isRelative,
+    isAnchor:          isAnchor,
+    normalize:         normalize,
+    toAbsolute:        toAbsolute,
+    relative:          relative,
+    relativeForFile:   relativeForFile,
+    flatten:           flatten
 };