node package manager



Build Status

GitBook is a command line tool (and Node.js library) for building beautiful books and exercises using GitHub/Git and Markdown. You can see an example: Learn Javascript. An editor is available for Windows, Mac and Linux. You can follow @GitBookIO on Twitter.


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, pdf, json
--config <config file>    Configuration file to use, defaults to book.json

GitBook load 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 override the value from the command line)
    "output": null,
    // Generator to use for building (caution: it override the value from the command line)
    "generator": "site",
    // Book title and description (defaults are extracted from the README)
    "title": null,
    "description": null,
    // GitHub informations (defaults are extracted using git)
    "github": null,
    "githubHost": "",
    // 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
    // set another theme with your own layout
    // it's recommended to use plugins or add more options for default theme, though
    // see
    "theme": "./localtheme",
    // Links in template (null: default, false: remove, string: new value)
    "links": {
        // Link to home in the top-left corner
        "home": null,
        // Links in top of sidebar
        "about": null,
        "issues": null,
        "contribute": null,
        // Sharing links
        "sharing": {
            "google": null,
            "facebook": null,
            "twitter": null

You can publish your books to our index by visiting

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.
  • PDF: A complete PDF book with exercise solutions at the end of the book. Generate to this format using: gitbook pdf ./myrepo, you need to have gitbook-pdf installed.
  • eBook: A complete eBook with exercise solutions at the end of the book. Generate to this format using: gitbook ebook ./myrepo, you need to have ebook-convert installed.
  • Single Page: The book will be stored in a single printable HTML page, this format is used for conversion to PDF or eBook. Generate to this format using: gitbook build ./myrepo -f page.
  • JSON: This format is used for debugging or extracting metadata from a book. Generate to this format using: gitbook build ./myrepo -f json.

Book Format

A book is a Git repository containing at least 2 files: and

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

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


# Summary
This is the summary of my book.
* [section 1](section1/
    * [example 1](section1/
    * [example 2](section1/
* [section 2](section2/
    * [example 1](section2/

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


A book can contain interactive exercises (currently only in Javascript but Python and Ruby are coming soon ;) ). An exercise is a code challenge provided to the reader, which is given a code editor to write a solution which is checked against the book author's validation code.

An exercise is defined by 4 simple parts:

  • Exercise Message/Goals (in markdown/text)
  • Initial code to show to the user, providing a starting point
  • Solution code, being a correct solution to the exercise
  • Validation code that tests the correctness of the user's input

Exercises need to start and finish with a separation bar (--- or ***). It should contain 3 code elements (base, solution and validation). It can contain a 4th element that provides context code (functions, imports of libraries etc ... that shouldn't be displayed to the user).


Define a variable `x` equal to 10.

var x =

var x = 10;

assert(x == 10);

// This is context code available everywhere
// The user will be able to call magicFunc in his code
function magicFunc() {
    return 3;



GitBook supports building books written in multiple languages. Each language should be a sub-directory following the normal GitBook format, and a file named 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.

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)


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 is like an "Heroku for books", you can create a book on it (public, paid, or private) and update it using git push.


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

Default plugins:
  • mathjax: displays mathematical notation in the book.
  • mixpanel: Mixpanel tracking for your book
Other plugins: