GitBook

GitBook is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown. Here is an example: Learn Javascript. You can publish book easily online using gitbook.io and an editor is available for Windows, Mac and Linux. You can follow @GitBookIO on Twitter. Complete documentation is available at help.gitbook.io.

How to use it:

GitBook can be installed from NPM using:

$ npm install gitbook -g

You can serve a repository as a book using:

$ gitbook serve ./repository

Or simply build the static website using:

$ gitbook build ./repository --output=./outputFolder

Options for commands build and serve are:

-o, --output <directory>  Path to output directory, defaults to ./_book
-f, --format <name>       Change generation format, defaults to site, availables are: site, page, ebook, json
--config <config file>    Configuration file to use, defaults to book.js or book.json

GitBook loads the default configuration from a book.json file in the repository if it exists.

Here are the options that can be stored in this file:

{
    // Folders to use for output
    // Caution: it overrides the value from the command line
    // It's not advised this option in the book.json
    "output": null,

    // Generator to use for building
    // Caution: it overrides the value from the command line
    // It's not advised this option in the book.json
    "generator": "site",

    // Book title and description (defaults are extracted from the README)
    "title": null,
    "description": null,

    // For ebook format, the extension to use for generation (default is detected from output extension)
    // "epub", "pdf", "mobi"
    // Caution: it overrides the value from the command line
    // It's not advised this option in the book.json
    "extension": null,

    // GitHub information (defaults are extracted using git)
    "github": null,
    "githubHost": "https://github.com/",

    // Plugins list, can contain "-name" for removing default plugins
    "plugins": [],

    // Global configuration for plugins
    "pluginsConfig": {
        "fontSettings": {
            "theme": "sepia", "night" or "white",
            "family": "serif" or "sans",
            "size": 1 to 4
        }
    },

    // Links in template (null: default, false: remove, string: new value)
    "links": {
    	// Custom links at top of sidebar
    	"sidebar": {
    	    "Custom link name": "https://customlink.com"
    	},

        // Sharing links
        "sharing": {
            "google": null,
            "facebook": null,
            "twitter": null,
            "weibo": null,
            "all": null
        }
    },


    // Options for PDF generation
    "pdf": {
        // Add toc at the end of the file
        "toc": true,

        // Add page numbers to the bottom of every page
        "pageNumbers": false,

        // Font size for the fiel content
        "fontSize": 12,

        // 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’]
        "paperSize": "a4",

        // Margin (in pts)
        // Note: 72 pts equals 1 inch
        "margin": {
            "right": 62,
            "left": 62,
            "top": 36,
            "bottom": 36
        }
    }
}

You can publish your books to our index by visiting GitBook.io

Output Formats

GitBook can generate your book in the following formats:

• Static Website: This is the default format. It generates a complete interactive static website that can be, for example, hosted on GitHub Pages.
• eBook: A complete eBook with exercise solutions at the end of the book. Generate this format using: gitbook ebook ./myrepo. You need to have ebook-convert installed. The output format could be PDF, ePub or MOBI.
• Single Page: The book will be stored in a single printable HTML page. This format is used for conversion to PDF or eBook. Generate this format using: gitbook build ./myrepo -f page.
• JSON: This format is used for debugging or extracting metadata from a book. Generate this format using: gitbook build ./myrepo -f json.

Book Format

A book is a Git repository containing at least 2 files: README.md and SUMMARY.md.

README.md

Typically, this should be the introduction for your book. It will be automatically added to the final summary.

SUMMARY.md

The SUMMARY.md defines your book's structure. It should contain a list of chapters, linking to their respective pages.

Example:

# Summary

This is the summary of my book.

* [section 1](section1/README.md)
    * [example 1](section1/example1.md)
    * [example 2](section1/example2.md)
* [section 2](section2/README.md)
    * [example 1](section2/example1.md)

Files that are not included in SUMMARY.md will not be processed by gitbook.

Multi-Languages

GitBook supports building books written in multiple languages. Each language should be a sub-directory following the normal GitBook format, and a file named LANGS.md should be present at the root of the repository with the following format:

* [English](en/)
* [French](fr/)
* [Español](es/)

You can see a complete example with the Learn Git book.

Glossary

Allows you to specify terms and their respective definitions to be displayed in the glossary. Based on those terms, gitbook will automatically build an index and highlight those terms in pages.

The GLOSSARY.md format is very simple :

# term
Definition for this term

# Another term
With it's definition, this can contain bold text and all other kinds of inline markup ...

Ignoring files & folders

GitBook will read the .gitignore, .bookignore and .ignore files to get a list of files and folders to skip. (The format inside those files follows the same convention as .gitignore).

Best practices for the .gitignore is to ignore build files from node.js (node_modules, ...) and build files from GitBook: _book, *.epub, *.mobi and *.pdf.

Cover

A cover image can be set by creating a file: /cover.jpg. The best resolution is 1800x2360. The generation of the cover can be done automatically using the plugin autocover.

A small version of the cover can also be set by creating a file: /cover_small.jpg.

Publish your book

The platform GitBook.io is like an "Heroku for books": you can create a book on it (public, paid, or private) and update it using git push.

Plugins

Plugins can used to extend your book's functionality. Read GitbookIO/plugin for more information about how to build a plugin for GitBook.

Official plugins:

Other plugins:

Debugging

You can use the environment variable DEBUG=true to get better error messages (with stack trace). For example:

$ export DEBUG=true
$ gitbook build ./