Bump version to 2.5.0-beta.6

Fix #982: correctly handle templating in imported content

CHANGES.md

@@ -2,6 +2,26 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## 2.5.0-beta.6
+- Fix default style for pdf footer and header
+- Correctly handle query in image urls
+- Fix templating in imported content
+- Use helvetica as default font for PDFs
+
+## 2.5.0-beta.5
+- Fix position of sidebar toggle button
+- Update asciidoc parser to remove git dependency
+
+## 2.5.0-beta.4
+- Fix compatibility for some plugins (like `autocover`)
+- Fix position of sidebar toggle button when glossary button is present
+
+## 2.5.0-beta.3
+- Fix installation of plugins when using a pre-release
+
+## 2.5.0-beta.2
+- Fix support for pre-releases
+
 ## 2.5.0-beta.1
 - Font settings, sharing and search are externalized as default plugins
 - Plugins can define a configuration schema in the manifest, this schema will be used to validate configuration during build

README.md

@@ -222,9 +222,9 @@ To use the latest commit from `GitBook/gitbook` with `gitbook-cli`:
 
 ```
 $ git clone https://github.com/GitbookIO/gitbook.git ./gitbook
-$ gitbook versions:link 2.0.0 ./gitbook
+$ gitbook versions:link ./gitbook
 ```
 
-Now the version tag `2.0.0` wil be associated with the `./gitbook` folder.
+Now `gitbook-cli` will be using the `./gitbook` folder.
 
-You can uninstall it using: `gitbook versions:uninstall 2.0.0`.
+You can uninstall it using: `gitbook versions:uninstall latest`.

lib/config_default.js

@@ -75,8 +75,9 @@ module.exports = {
         // Add page numbers to the bottom of every page
         'pageNumbers': false,
 
-        // Font size for the file content
+        // Font for the file content
         'fontSize': 12,
+        'fontFamily': 'Helvetica',
 
         // Paper size for the pdf
         // Choices are [u’a0’, u’a1’, u’a2’, u’a3’, u’a4’, u’a5’, u’a6’, u’b0’, u’b1’, u’b2’, u’b3’, u’b4’, u’b5’, u’b6’, u’legal’, u’letter’]

lib/configuration.js

@@ -5,6 +5,7 @@ var semver = require('semver');
 
 var pkg = require('../package.json');
 var i18n = require('./utils/i18n');
+var version = require('./version');
 
 var DEFAULT_CONFIG = require('./config_default');
 
@@ -83,31 +84,8 @@ function normalizePluginsList(plugins, addDefaults) {
 }
 
 var Configuration = function(book, options) {
-    var that = this;
-
     this.book = book;
     this.replace(options);
-
-    // options.input == book.root
-    Object.defineProperty(this.options, 'input', {
-        get: function () {
-            return that.book.root;
-        }
-    });
-
-    // options.originalInput == book.parent.root
-    Object.defineProperty(this.options, 'originalInput', {
-        get: function () {
-            return that.book.parent? that.book.parent.root : undefined;
-        }
-    });
-
-    // options.originalOutput == book.parent.options.output
-    Object.defineProperty(this.options, 'originalOutput', {
-        get: function () {
-            return that.book.parent? that.book.parent.options.output : undefined;
-        }
-    });
 };
 
 // Read and parse the configuration
@@ -139,7 +117,7 @@ Configuration.prototype.load = function() {
     })
     .then(function() {
         if (!that.book.isSubBook()) {
-            if (!semver.satisfies(pkg.version, that.options.gitbook)) {
+            if (!version.satisfies(that.options.gitbook)) {
                 throw new Error('GitBook version doesn\'t satisfy version required by the book: '+that.options.gitbook);
             }
             if (that.options.gitbook != '*' && !semver.satisfies(semver.inc(pkg.version, 'patch'), that.options.gitbook)) {
@@ -170,8 +148,31 @@ Configuration.prototype.extend = function(options) {
 
 // Replace the whole configuration
 Configuration.prototype.replace = function(options) {
+    var that = this;
+
     this.options = _.cloneDeep(DEFAULT_CONFIG);
     this.options = _.merge(this.options, options || {});
+
+    // options.input == book.root
+    Object.defineProperty(this.options, 'input', {
+        get: function () {
+            return that.book.root;
+        }
+    });
+
+    // options.originalInput == book.parent.root
+    Object.defineProperty(this.options, 'originalInput', {
+        get: function () {
+            return that.book.parent? that.book.parent.root : undefined;
+        }
+    });
+
+    // options.originalOutput == book.parent.options.output
+    Object.defineProperty(this.options, 'originalOutput', {
+        get: function () {
+            return that.book.parent? that.book.parent.options.output : undefined;
+        }
+    });
 };
 
 // Dump configuration as json object

lib/conrefs_loader.js

@@ -1,15 +1,19 @@
-var path = require("path");
-var nunjucks = require("nunjucks");
+var _ = require('lodash');
+var path = require('path');
+var nunjucks = require('nunjucks');
 
-var git = require("./utils/git");
-var fs = require("./utils/fs");
-var pathUtil = require("./utils/path");
+var git = require('./utils/git');
+var fs = require('./utils/fs');
+var pathUtil = require('./utils/path');
 
 // The loader should handle relative and git url
 var BookLoader = nunjucks.Loader.extend({
     async: true,
 
-    init: function(book) {
+    init: function(book, opts) {
+        this.opts = _.defaults(opts || {}, {
+            interpolate: _.identity
+        });
         this.book = book;
     },
 
@@ -20,14 +24,20 @@ var BookLoader = nunjucks.Loader.extend({
         .then(function(filepath) {
             // Is local file
             if (!filepath) filepath = path.resolve(fileurl);
-            else that.book.log.debug.ln("resolve from git", fileurl, "to", filepath);
+            else that.book.log.debug.ln('resolve from git', fileurl, 'to', filepath);
 
             //  Read file from absolute path
             return fs.readFile(filepath)
+            .then(function(source) {
+                return that.opts.interpolate(filepath, source.toString());
+            })
             .then(function(source) {
                 return {
-                    src: source.toString(),
-                    path: filepath
+                    src: source,
+                    path: filepath,
+
+                    // We disable cache sincde content is modified (shortcuts, ...)
+                    noCache: true
                 };
             });
         })
@@ -53,7 +63,7 @@ var BookLoader = nunjucks.Loader.extend({
         return path.resolve(path.dirname(from), to);
     },
 
-    // Handle all files as relative, so that nunjucks pass responsability to "resolve"
+    // Handle all files as relative, so that nunjucks pass responsability to 'resolve'
     // Only git urls are considered as absolute
     isRelative: function(filename) {
         return !git.checkUrl(filename);

lib/generators/ebook.js

@@ -46,7 +46,7 @@ Generator.prototype.writeSummary = function() {
 Generator.prototype.getPDFTemplate = function(id) {
     var tpl = this.options.pdf[id+'Template'];
     var defaultTpl = path.resolve(this.options.theme, 'templates/ebook/'+id+'.html');
-    var defaultCSS = path.resolve(this.options.theme, 'assets/pdf.css');
+    var defaultCSS = path.resolve(this.options.theme, 'assets/ebook/pdf.css');
 
     // Default template from theme
     if (!tpl && fs.existsSync(defaultTpl)) {
@@ -123,7 +123,8 @@ Generator.prototype.finish = function() {
                 '--paper-size': String(pdfOptions.paperSize),
                 '--pdf-page-numbers': Boolean(pdfOptions.pageNumbers),
                 '--pdf-header-template': that.getPDFTemplate('header'),
-                '--pdf-footer-template': that.getPDFTemplate('footer')
+                '--pdf-footer-template': that.getPDFTemplate('footer'),
+                '--pdf-sans-family': String(pdfOptions.fontFamily)
             });
         } else if (that.ebookFormat == 'epub') {
             _.extend(_options, {

lib/plugin.js

@@ -1,6 +1,5 @@
 var _ = require('lodash');
 var Q = require('q');
-var semver = require('semver');
 var path = require('path');
 var url = require('url');
 var fs = require('./utils/fs');
@@ -9,7 +8,7 @@ var mergeDefaults = require('merge-defaults');
 var jsonschema = require('jsonschema');
 var jsonSchemaDefaults = require('json-schema-defaults');
 
-var pkg = require('../package.json');
+var version = require('./version');
 
 var PLUGIN_PREFIX = 'gitbook-plugin-';
 
@@ -145,7 +144,7 @@ Plugin.prototype.isValid = function() {
         this.packageInfos.name &&
         this.packageInfos.engines &&
         this.packageInfos.engines.gitbook &&
-        semver.satisfies(pkg.version, this.packageInfos.engines.gitbook)
+        version.satisfies(this.packageInfos.engines.gitbook)
     );
 
     // Valid hooks

lib/pluginslist.js

@@ -5,7 +5,7 @@ var npm = require('npm');
 var semver = require('semver');
 
 var Plugin = require('./plugin');
-var pkg = require('../package.json');
+var version = require('./version');
 
 var initNPM = _.memoize(function() {
     return Q.nfcall(npm.load, { silent: true, loglevel: 'silent' });
@@ -191,7 +191,7 @@ PluginsList.prototype.install = function() {
                             };
                         })
                         .filter(function(v) {
-                            return v.gitbook && semver.satisfies(pkg.version, v.gitbook);
+                            return v.gitbook && version.satisfies(v.gitbook);
                         })
                         .sort(function(v1, v2) {
                             return semver.lt(v1.version, v2.version)? 1 : -1;

lib/template.js

@@ -1,12 +1,14 @@
-var _ = require("lodash");
-var Q = require("q");
-var nunjucks = require("nunjucks");
-var escapeStringRegexp = require("escape-string-regexp");
+var _ = require('lodash');
+var Q = require('q');
+var path = require('path');
+var nunjucks = require('nunjucks');
+var parsers = require('gitbook-parsers');
+var escapeStringRegexp = require('escape-string-regexp');
 
-var batch = require("./utils/batch");
-var pkg = require("../package.json");
-var defaultBlocks = require("./blocks");
-var BookLoader = require("./conrefs_loader");
+var batch = require('./utils/batch');
+var pkg = require('../package.json');
+var defaultBlocks = require('./blocks');
+var BookLoader = require('./conrefs_loader');
 
 // Normalize result from a block
 function normBlockResult(blk) {
@@ -16,24 +18,37 @@ function normBlockResult(blk) {
 
 
 var TemplateEngine = function(book) {
+    var that = this;
+
     this.book = book;
     this.log = this.book.log;
 
+    // Template loader
+    this.loader = new BookLoader(book, {
+        // Replace shortcuts in imported files
+        interpolate: function(filepath, source) {
+            var parser = parsers.get(path.extname(filepath));
+            var type = parser? parser.name : null;
+
+            return  that.applyShortcuts(type, source);
+        }
+    });
+
     // Nunjucks env
     this.env = new nunjucks.Environment(
-        new BookLoader(book),
+        this.loader,
         {
             // Escaping is done after by the markdown parser
             autoescape: false,
 
             // Tags
             tags: {
-                blockStart: "{%",
-                blockEnd: "%}",
-                variableStart: "{{",
-                variableEnd: "}}",
-                commentStart: "{###",
-                commentEnd: "###}"
+                blockStart: '{%',
+                blockEnd: '%}',
+                variableStart: '{{',
+                variableEnd: '}}',
+                commentStart: '{###',
+                commentEnd: '###}'
             }
         }
     );
@@ -60,20 +75,20 @@ TemplateEngine.prototype.processBlock = function(blk) {
         parse: false,
         post: undefined
     });
-    blk.id = _.uniqueId("blk");
+    blk.id = _.uniqueId('blk');
 
     var toAdd = (!blk.parse) || (blk.post !== undefined);
 
     // Add to global map
     if (toAdd) this.blockBodies[blk.id] = blk;
 
-    //Parsable block, just return it
+    // Parsable block, just return it
     if (blk.parse) {
         return blk.body;
     }
 
     // Return it as a position marker
-    return "@%@"+blk.id+"@%@";
+    return '@%@'+blk.id+'@%@';
 };
 
 // Replace position markers of blocks by body after processing
@@ -110,11 +125,13 @@ TemplateEngine.prototype.bindContext = function(func) {
 TemplateEngine.prototype.addFilter = function(filterName, func) {
     try {
         this.env.getFilter(filterName);
-        this.log.warn.ln("conflict in filters, \""+filterName+"\" is already set");
+        this.log.warn.ln('conflict in filters, \''+filterName+'\' is already set');
         return false;
-    } catch(e) {}
+    } catch(e) {
+        // Filter doesn't exist
+    }
 
-    this.log.debug.ln("add filter \""+filterName+"\"");
+    this.log.debug.ln('add filter \''+filterName+'\'');
     this.env.addFilter(filterName, this.bindContext(function() {
         var ctx = this;
         var args = Array.prototype.slice.apply(arguments);
@@ -138,7 +155,7 @@ TemplateEngine.prototype.addFilters = function(filters) {
 
 // Return nunjucks extension name of a block
 TemplateEngine.prototype.blockExtName = function(name) {
-    return "Block"+name+"Extension";
+    return 'Block'+name+'Extension';
 };
 
 // Test if a block is defined
@@ -167,7 +184,7 @@ TemplateEngine.prototype.addBlock = function(name, block) {
 
     block = _.defaults(block || {}, {
         shortcuts: [],
-        end: "end"+name,
+        end: 'end'+name,
         process: _.identity,
         blocks: []
     });
@@ -175,13 +192,13 @@ TemplateEngine.prototype.addBlock = function(name, block) {
     extName = this.blockExtName(name);
 
     if (this.hasBlock(name) && !defaultBlocks[name]) {
-        this.log.warn.ln("conflict in blocks, \""+name+"\" is already defined");
+        this.log.warn.ln('conflict in blocks, \''+name+'\' is already defined');
     }
 
     // Cleanup previous block
     this.removeBlock(name);
 
-    this.log.debug.ln("add block \""+name+"\"");
+    this.log.debug.ln('add block \''+name+'\'');
     this.blocks[name] = block;
 
     Ext = function () {
@@ -238,7 +255,7 @@ TemplateEngine.prototype.addBlock = function(name, block) {
                 bodies.push(subbodies[blockName][0].body);
             });
 
-            return new nodes.CallExtensionAsync(this, "run", args, bodies);
+            return new nodes.CallExtensionAsync(this, 'run', args, bodies);
         };
 
         this.run = function(context) {
@@ -287,7 +304,7 @@ TemplateEngine.prototype.addBlock = function(name, block) {
     // Add shortcuts
     if (!_.isArray(block.shortcuts)) block.shortcuts = [block.shortcuts];
     _.each(block.shortcuts, function(shortcut) {
-        this.log.debug.ln("add template shortcut from \""+shortcut.start+"\" to block \""+name+"\" for parsers ", shortcut.parsers);
+        this.log.debug.ln('add template shortcut from \''+shortcut.start+'\' to block \''+name+'\' for parsers ', shortcut.parsers);
         this.shortcuts.push({
             block: name,
             parsers: shortcut.parsers,
@@ -314,7 +331,7 @@ TemplateEngine.prototype.applyBlock = function(name, blk, ctx) {
     var func, block, r;
 
     block = this.blocks[name];
-    if (!block) throw new Error("Block not found \""+name+"\"");
+    if (!block) throw new Error('Block not found \''+name+'\'');
     if (_.isString(blk)) {
         blk = {
             body: blk
@@ -339,14 +356,19 @@ TemplateEngine.prototype.applyBlock = function(name, blk, ctx) {
 TemplateEngine.prototype._applyShortcut = function(parser, content, shortcut) {
     if (!_.contains(shortcut.parsers, parser)) return content;
     var regex = new RegExp(
-        escapeStringRegexp(shortcut.start) + "([\\s\\S]*?[^\\$])" + escapeStringRegexp(shortcut.end),
-       "g"
+        escapeStringRegexp(shortcut.start) + '([\\s\\S]*?[^\\$])' + escapeStringRegexp(shortcut.end),
+       'g'
     );
     return content.replace(regex, function(all, match) {
-        return "{% "+shortcut.tag.start+" %}"+ match + "{% "+shortcut.tag.end+" %}";
+        return '{% '+shortcut.tag.start+' %}'+ match + '{% '+shortcut.tag.end+' %}';
     });
 };
 
+// Apply all shortcuts to some template string
+TemplateEngine.prototype.applyShortcuts = function(type, content) {
+    return _.reduce(this.shortcuts, _.partial(this._applyShortcut.bind(this), type), content);
+};
+
 // Render a string from the book
 TemplateEngine.prototype.renderString = function(content, context, options) {
     context = _.extend({}, context, {
@@ -367,14 +389,18 @@ TemplateEngine.prototype.renderString = function(content, context, options) {
         type: null
     });
     if (options.path) options.path = this.book.resolve(options.path);
+    if (!options.type && options.path) {
+        var parser = parsers.get(path.extname(options.path));
+        options.type = parser? parser.name : null;
+    }
 
     // Replace shortcuts
-    content = _.reduce(this.shortcuts, _.partial(this._applyShortcut.bind(this), options.type), content);
+    content = this.applyShortcuts(options.type, content);
 
     return Q.nfcall(this.env.renderString.bind(this.env), content, context, options)
     .fail(function(err) {
         if (_.isString(err)) err = new Error(err);
-        err.message = err.message.replace(/^Error: /, "");
+        err.message = err.message.replace(/^Error: /, '');
 
         throw err;
     });
@@ -398,7 +424,7 @@ TemplateEngine.prototype.renderPage = function(page) {
 
     return that.book.statFile(page.path)
     .then(function(stat) {
-       var context = {
+        var context = {
             // infos about the file
             file: {
                 path: page.path,

lib/utils/page.js

@@ -132,7 +132,7 @@ function normalizeHtml(src, options) {
             // If image is external and ebook, then downlaod the images
             if (isExternal) {
                 origin = src;
-                src = '/'+crc.crc32(origin).toString(16)+path.extname(origin);
+                src = '/'+crc.crc32(origin).toString(16)+path.extname(url.parse(origin).pathname);
                 src = links.toAbsolute(src, options.base, options.output);
                 isExternal = false;
             }

lib/version.js

@@ -0,0 +1,19 @@
+var semver = require('semver');
+var pkg = require('../package.json');
+
+var VERSION = pkg.version;
+var VERSION_STABLE = VERSION.replace(/\-(\S+)/g, '');
+
+// Test if current current gitbook version satisfies a condition
+// We can't directly use samver.satisfies since it will break all plugins when gitbook version is a prerelease (beta, alpha)
+function satisfies(condition) {
+    // Test with real version
+    if (semver.satisfies(VERSION, condition)) return true;
+
+    // Test with future stable release
+    return semver.satisfies(VERSION_STABLE, condition);
+}
+
+module.exports = {
+    satisfies: satisfies
+};

package.json

@@ -1,6 +1,6 @@
 {
     "name": "gitbook",
-    "version": "2.5.0-beta.1",
+    "version": "2.5.0-beta.6",
     "homepage": "https://www.gitbook.com",
     "description": "Library and cmd utility to generate GitBooks",
     "main": "lib/index.js",
@@ -11,7 +11,7 @@
         "resolve": "0.6.3",
         "fs-extra": "0.16.5",
         "fstream-ignore": "1.0.2",
-        "gitbook-parsers": "0.8.4",
+        "gitbook-parsers": "0.8.5",
         "gitbook-plugin-highlight": "1.0.3",
         "gitbook-plugin-sharing": "1.0.1",
         "gitbook-plugin-search": "1.0.2",

test/books/conrefs/README.md

@@ -1,5 +1,8 @@
 # Readme
 
+<p id="test-plugin-block-shortcuts-1">$$test_block1$$</p>
+<p id="test-plugin-block-shortcuts-2">{% include "./block.md" %}</p>
+
 ### Relative
 
 <p id="t1">{% include "./hello.md" %}</p>

test/books/conrefs/block.md

@@ -0,0 +1 @@
+$$test_block2$$

test/conrefs.js

@@ -1,66 +1,66 @@
-var fs = require("fs");
-var path = require("path");
+var fs = require('fs');
+var path = require('path');
 
-describe("ConRefs", function () {
+describe('ConRefs', function () {
     var book, readme;
 
     before(function() {
-        return books.generate("conrefs", "website")
+        return books.generate('conrefs', 'website')
             .then(function(_book) {
                 book = _book;
 
                 readme = fs.readFileSync(
-                    path.join(book.options.output, "index.html"),
-                    { encoding: "utf-8" }
+                    path.join(book.options.output, 'index.html'),
+                    { encoding: 'utf-8' }
                 );
             });
     });
 
-    it("should handle local references", function() {
+    it('should handle local references', function() {
         readme.should.be.html({
-            ".page-inner p#t1": {
+            '.page-inner p#t1': {
                 count: 1,
-                text: "Hello World",
+                text: 'Hello World',
                 trim: true
             }
         });
     });
 
-    it("should handle local references with absolute paths", function() {
+    it('should handle local references with absolute paths', function() {
         readme.should.be.html({
-            ".page-inner p#t2": {
+            '.page-inner p#t2': {
                 count: 1,
-                text: "Hello World",
+                text: 'Hello World',
                 trim: true
             }
         });
     });
 
-    it("should correctly include file from git reference", function() {
+    it('should correctly include file from git reference', function() {
         readme.should.be.html({
-            ".page-inner p#t3": {
+            '.page-inner p#t3': {
                 count: 1,
-                text: "Hello from git",
+                text: 'Hello from git',
                 trim: true
             }
         });
     });
 
-    it("should correctly handle deep include in git reference", function() {
+    it('should correctly handle deep include in git reference', function() {
         readme.should.be.html({
-            ".page-inner p#t4": {
+            '.page-inner p#t4': {
                 count: 1,
-                text: "First Hello. Hello from git",
+                text: 'First Hello. Hello from git',
                 trim: true
             }
         });
     });
 
-    it("should correctly handle absolute include in git reference", function() {
+    it('should correctly handle absolute include in git reference', function() {
         readme.should.be.html({
-            ".page-inner p#t5": {
+            '.page-inner p#t5': {
                 count: 1,
-                text: "First Hello. Hello from git",
+                text: 'First Hello. Hello from git',
                 trim: true
             }
         });

test/helper.js

@@ -1,13 +1,13 @@
-var os = require("os");
-var path = require("path");
-var Q = require("q");
-var _ = require("lodash");
+var os = require('os');
+var path = require('path');
+var Q = require('q');
+var _ = require('lodash');
 
-var fsUtil = require("../lib/utils/fs");
-var Book = require("../").Book;
-var LOG_LEVELS = require("../").LOG_LEVELS;
+var fsUtil = require('../lib/utils/fs');
+var Book = require('../').Book;
+var LOG_LEVELS = require('../').LOG_LEVELS;
 
-require("./assertions");
+require('./assertions');
 
 
 var BOOKS = {};
@@ -20,7 +20,7 @@ function generateBook(bookId, test, opts) {
         prepare: function() {}
     });
 
-    return parseBook(bookId, test)
+    return parseBook(bookId, test, opts)
     .then(function(book) {
 
         return Q(opts.prepare(book))
@@ -32,21 +32,27 @@ function generateBook(bookId, test, opts) {
 }
 
 // Generate and return a book
-function parseBook(bookId, test) {
-    test = test || "website";
-    BOOKS[bookId] = BOOKS[bookId] || {};
-    if (BOOKS[bookId][test]) return Q(BOOKS[bookId][test]);
+function parseBook(bookId, test, opts) {
+    opts = _.defaults(opts || {}, {
+        testId: ''
+    });
 
-    BOOKS[bookId][test] = new Book(path.resolve(__dirname, "books", bookId), {
+    test = test || 'website';
+    var testId = [test, opts.testId].join('-');
+
+    BOOKS[bookId] = BOOKS[bookId] || {};
+    if (BOOKS[bookId][testId]) return Q(BOOKS[bookId][testId]);
+
+    BOOKS[bookId][testId] = new Book(path.resolve(__dirname, 'books', bookId), {
         logLevel: LOG_LEVELS.DISABLED,
         config: {
-            output: path.resolve(TMPDIR, bookId+"-"+test)
+            output: path.resolve(TMPDIR, bookId+'-'+testId)
         }
     });
 
-    return BOOKS[bookId][test].parse()
+    return BOOKS[bookId][testId].parse()
     .then(function() {
-        return BOOKS[bookId][test];
+        return BOOKS[bookId][testId];
     });
 }
 

test/plugins.js

@@ -1,4 +1,5 @@
 var _ = require('lodash');
+var fs = require('fs');
 var should = require('should');
 var path = require('path');
 
@@ -193,15 +194,49 @@ describe('Plugins', function () {
                 });
         });
 
-        it('should correctly accept shortcuts', function() {
-            return testTpl('$$hello$$', {}, {
-                type: 'markdown'
-            })
-            .then(function(content) {
-                content.should.equal('testhellotest');
+        describe('Shortcuts', function() {
+            it('should correctly accept shortcuts', function() {
+                return testTpl('$$hello$$', {}, {
+                    type: 'markdown'
+                })
+                .then(function(content) {
+                    content.should.equal('testhellotest');
+                });
+            });
+
+            it('should correctly apply shortcuts to included file', function() {
+                return books.generate('conrefs', 'website', {
+                    testId: 'include-plugins',
+                    prepare: function(bookConref) {
+                        plugin = new Plugin(bookConref, 'blocks');
+                        plugin.load('./blocks', PLUGINS_ROOT);
+
+                        return bookConref.plugins.load(plugin);
+                    }
+                })
+                .then(function(bookConref) {
+                    var readme = fs.readFileSync(
+                        path.join(bookConref.options.output, 'index.html'),
+                        { encoding: 'utf-8' }
+                    );
+
+                    readme.should.be.html({
+                        '.page-inner p#test-plugin-block-shortcuts-1': {
+                            count: 1,
+                            text: 'testtest_block1test',
+                            trim: true
+                        },
+                        '.page-inner p#test-plugin-block-shortcuts-2': {
+                            count: 1,
+                            text: 'testtest_block2test',
+                            trim: true
+                        }
+                    });
+                });
             });
         });
 
+
         it('should correctly extend template blocks with defined end', function() {
             return testTpl('{% test2 %}hello{% endtest2end %}')
                 .then(function(content) {

theme/assets/website/app.js

@@ -24073,6 +24073,7 @@ function start(config) {
 
     // Add action to toggle sidebar
     toolbar.createButton({
+        index: 0,
         icon: 'fa fa-align-justify',
         onClick: function(e) {
             e.preventDefault();
@@ -24466,6 +24467,18 @@ var events = require('./events');
 // List of created buttons
 var buttons = [];
 
+// Insert a jquery element at a specific position
+function insertAt(parent, selector, index, element) {
+    var lastIndex = parent.children(selector).size();
+    if (index < 0) {
+        index = Math.max(0, lastIndex + 1 + index);
+    }
+    parent.append(element);
+
+    if (index < lastIndex) {
+        parent.children(selector).eq(index).before(parent.children(selector).last());
+    }
+}
 
 // Default click handler
 function defaultOnClick(e) {
@@ -24543,7 +24556,10 @@ function createButton(opts) {
         onClick: defaultOnClick,
 
         // Button is a dropdown
-        dropdown: null
+        dropdown: null,
+
+        // Position in the toolbar
+        index: null
     });
 
     buttons.push(opts);
@@ -24552,6 +24568,7 @@ function createButton(opts) {
 
 // Update a button
 function updateButton(opts) {
+    var $result;
     var $toolbar = $('.book-header');
     var $title = $toolbar.find('h1');
 
@@ -24593,12 +24610,17 @@ function updateButton(opts) {
         $menu.addClass('dropdown-'+(opts.position == 'right'? 'left' : 'right'));
 
         $container.append($menu);
-
-        $container.insertBefore($title);
+        $result = $container;
     } else {
         $btn.addClass(positionClass);
         $btn.addClass(opts.className);
-        $btn.insertBefore($title);
+        $result = $btn;
+    }
+
+    if (_.isNumber(opts.index) && opts.index >= 0) {
+        insertAt($toolbar, '.btn, .dropdown, h1', opts.index, $result);
+    } else {
+        $result.insertBefore($title);
     }
 }
 

theme/javascript/index.js

@@ -27,6 +27,7 @@ function start(config) {
 
     // Add action to toggle sidebar
     toolbar.createButton({
+        index: 0,
         icon: 'fa fa-align-justify',
         onClick: function(e) {
             e.preventDefault();

theme/javascript/toolbar.js

@@ -6,6 +6,18 @@ var events = require('./events');
 // List of created buttons
 var buttons = [];
 
+// Insert a jquery element at a specific position
+function insertAt(parent, selector, index, element) {
+    var lastIndex = parent.children(selector).size();
+    if (index < 0) {
+        index = Math.max(0, lastIndex + 1 + index);
+    }
+    parent.append(element);
+
+    if (index < lastIndex) {
+        parent.children(selector).eq(index).before(parent.children(selector).last());
+    }
+}
 
 // Default click handler
 function defaultOnClick(e) {
@@ -83,7 +95,10 @@ function createButton(opts) {
         onClick: defaultOnClick,
 
         // Button is a dropdown
-        dropdown: null
+        dropdown: null,
+
+        // Position in the toolbar
+        index: null
     });
 
     buttons.push(opts);
@@ -92,6 +107,7 @@ function createButton(opts) {
 
 // Update a button
 function updateButton(opts) {
+    var $result;
     var $toolbar = $('.book-header');
     var $title = $toolbar.find('h1');
 
@@ -133,12 +149,17 @@ function updateButton(opts) {
         $menu.addClass('dropdown-'+(opts.position == 'right'? 'left' : 'right'));
 
         $container.append($menu);
-
-        $container.insertBefore($title);
+        $result = $container;
     } else {
         $btn.addClass(positionClass);
         $btn.addClass(opts.className);
-        $btn.insertBefore($title);
+        $result = $btn;
+    }
+
+    if (_.isNumber(opts.index) && opts.index >= 0) {
+        insertAt($toolbar, '.btn, .dropdown, h1', opts.index, $result);
+    } else {
+        $result.insertBefore($title);
     }
 }