# gitbook

> Library and cmd utility to generate GitBooks

Latest version **2.6.9** (published 2018-10-11) · Apache-2.0 license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install gitbook
pnpm add gitbook
yarn add gitbook
bun add gitbook
```

Provides the command `gitbook`.

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 2.6.9 |
| Published | 2018-10-11 |
| First published | 2014-04-01 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 36 |
| Unpacked size | 2 MB |
| Known vulnerabilities | 2 (+27 in 7 direct dependencies) |
| Install scripts | no |
| GitHub stars | 29028 |
| Author | FriendCode Inc. |
| Maintainers | aarono, jpreynat, samypesse |
| Keywords | git, book, gitbook |

## Links

- npm: https://www.npmjs.com/package/gitbook
- Repository: https://github.com/GitbookIO/gitbook
- Homepage: https://www.gitbook.com
- Issues: https://github.com/GitbookIO/gitbook/issues
- npm.io page: https://npm.io/package/gitbook

## Dependencies (36)

- [q](https://npm.io/package/q.md) 1.0.1
- [crc](https://npm.io/package/crc.md) 3.2.1
- [npm](https://npm.io/package/npm.md) 2.4.1
- [tmp](https://npm.io/package/tmp.md) 0.0.24
- [i18n](https://npm.io/package/i18n.md) github:gitbookio/i18n-node#f26fbfa6b1d7a3bb086ff7849ca262f58a30255b
- [npmi](https://npm.io/package/npmi.md) 0.1.1
- [send](https://npm.io/package/send.md) github:gitbookio/send#9081de9cb0fc85d60e871685f252c98db764cb55
- [juice](https://npm.io/package/juice.md) 1.5.0
- [urijs](https://npm.io/package/urijs.md) 1.17.0
- [lodash](https://npm.io/package/lodash.md) 3.10.1
- [semver](https://npm.io/package/semver.md) 5.0.1
- [cheerio](https://npm.io/package/cheerio.md) 0.19.0
- [request](https://npm.io/package/request.md) 2.51.0
- [resolve](https://npm.io/package/resolve.md) 0.6.3
- [tiny-lr](https://npm.io/package/tiny-lr.md) 0.2.1
- [chokidar](https://npm.io/package/chokidar.md) ~1.0.5
- [fs-extra](https://npm.io/package/fs-extra.md) 0.16.5
- [nunjucks](https://npm.io/package/nunjucks.md) 2.2.0
- [spawn-cmd](https://npm.io/package/spawn-cmd.md) 0.0.2
- [bash-color](https://npm.io/package/bash-color.md) 0.0.3
- [jsonschema](https://npm.io/package/jsonschema.md) 1.0.2
- [graceful-fs](https://npm.io/package/graceful-fs.md) 3.0.5
- [github-slugid](https://npm.io/package/github-slugid.md) 1.0.0
- [dom-serializer](https://npm.io/package/dom-serializer.md) 0.1.0
- [fstream-ignore](https://npm.io/package/fstream-ignore.md) 1.0.2
- [merge-defaults](https://npm.io/package/merge-defaults.md) 0.2.1
- [gitbook-parsers](https://npm.io/package/gitbook-parsers.md) 0.8.9
- [nunjucks-filter](https://npm.io/package/nunjucks-filter.md) 1.0.0
- [nunjucks-autoescape](https://npm.io/package/nunjucks-autoescape.md) 1.0.0
- [escape-string-regexp](https://npm.io/package/escape-string-regexp.md) 1.0.3
- [json-schema-defaults](https://npm.io/package/json-schema-defaults.md) 0.1.1
- [gitbook-plugin-search](https://npm.io/package/gitbook-plugin-search.md) 1.1.0
- [gitbook-plugin-sharing](https://npm.io/package/gitbook-plugin-sharing.md) 1.0.1
- [gitbook-plugin-highlight](https://npm.io/package/gitbook-plugin-highlight.md) 1.0.3
- [gitbook-plugin-livereload](https://npm.io/package/gitbook-plugin-livereload.md) 0.0.1
- [gitbook-plugin-fontsettings](https://npm.io/package/gitbook-plugin-fontsettings.md) 1.0.2

## Recent versions

- 2.6.9 (latest) — 2018-10-11
- 4.0.0-alpha.6 (pre) — 2017-03-16
- 2.6.8 — 2018-10-10
- 3.2.3 — 2017-08-03
- 4.0.0-alpha.5 — 2017-03-09
- 4.0.0-alpha.4 — 2017-01-27
- 4.0.0-alpha.3 — 2017-01-13
- 4.0.0-alpha.2 — 2017-01-13
- 4.0.0-alpha.1 — 2017-01-13
- 3.2.2 — 2016-10-01
- 3.2.1 — 2016-09-28
- 3.2.0 — 2016-07-11
- 3.2.0-pre.1 — 2016-07-05
- 3.2.0-pre.0 — 2016-06-30
- 3.1.1 — 2016-06-10
- … 121 more at https://npm.io/package/gitbook/versions

## README

GitBook
=======

[![NPM version](https://badge.fury.io/js/gitbook.svg)](http://badge.fury.io/js/gitbook)
[![Linux Build Status](https://travis-ci.org/GitbookIO/gitbook.png?branch=master)](https://travis-ci.org/GitbookIO/gitbook)
[![Windows Build status](https://ci.appveyor.com/api/projects/status/63nlflxcwmb2pue6?svg=true)](https://ci.appveyor.com/project/GitBook/gitbook)
[![Slack Status](https://slack.gitbook.com/badge.svg)](https://slack.gitbook.com)

GitBook is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown (or AsciiDoc). Here is an example: [Learn Javascript](https://www.gitbook.com/book/GitBookIO/javascript).

You can publish and host books easily online using [gitbook.com](https://www.gitbook.com). A desktop editor is [also available](https://www.gitbook.com/editor).

Check out the [GitBook Community Slack Channel](https://slack.gitbook.com), Stay updated by following [@GitBookIO](https://twitter.com/GitBookIO) on Twitter or [GitBook](https://www.facebook.com/gitbookcom) on Facebook.

Complete documentation is available at [help.gitbook.com](http://help.gitbook.com/).

![Image](https://raw.github.com/GitbookIO/gitbook/master/preview.png)

## How to use it:

GitBook can be installed from **NPM** using:

```
$ npm install gitbook-cli -g
```

Create the directories and files for a book from its [SUMMARY.md](https://github.com/GitbookIO/gitbook#book-format) file (if existing) using

```
$ gitbook init
```

You can serve a repository as a book using:

```
$ gitbook serve
```

Or simply build the static website using:

```
$ gitbook build
```

## Features

* [Output as a website or ebook (pdf, epub, mobi)](http://help.gitbook.com/format/output.html)
* [Multi-Languages](http://help.gitbook.com/format/languages.html)
* [Glossary](http://help.gitbook.com/format/glossary.html)
* [Cover](http://help.gitbook.com/format/cover.html)
* [AsciiDoc Support](http://help.gitbook.com/format/asciidoc.html)
* [Variables and Templating](http://help.gitbook.com/format/templating.html)
* [Content References](http://help.gitbook.com/format/conrefs.html)
* [Plugins](http://help.gitbook.com/format/plugins.html)
* Interractive reader website:
    * Search
    * Font Settings (Serif, Sans Serif)
    * Themes: white, sepia, night

## 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**: You need to have [ebook-convert](http://manual.calibre-ebook.com/cli/ebook-convert.html) installed.  You can specify the eBook filename as the second argument, otherwise `book` will be used.
  * Generate a **PDF** using:  `gitbook pdf ./myrepo ./mybook.pdf`
  * Generate a **ePub** using: `gitbook epub ./myrepo ./mybook.epub`
  * Generate a **MOBI** using: `gitbook mobi ./myrepo ./mybook.mobi`
* **JSON**: This format is used for debugging or extracting metadata from a book. Generate this format using: ```gitbook build ./myrepo --format=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:

```markdown
# 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:

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

You can see a complete example with the [Learn Git](https://github.com/GitbookIO/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 :

```markdown
# term
Definition for this term

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

#### Variables and Templating

A set of variables can be defined in the `book.json`:

```js
{
    "variables": {
        "host": "mybook.com"
    }
}
```

These variables can be used in the markdown files:

```
The host is {{ book.host }}
```

You can also use condition with these variables:

```
{% if book.host == "mybook.com" %}

{% else %}

{% endif %}
```

Variables of `book.json` are available in the `book` namespace. You can also access informations about the `file` itself and the `gitbook` version:

```
My file is {{ file.path }}
Modified at {{ file.mtime }}
Book built with GitBook {{ gitbook.version }}
```

#### Content References

You can use "content references," or conrefs, when writing books or documentation using GitBook.

Include a file from the same book:

```
{% include "./test.md" %}
```

or from a git repository (with a specific revision):

```
{% include "git+https://github.com/GitbookIO/documentation.git/README.md#1.0.1" %}
```

Includes can be used with variables (see [Variables and Templating](#variables-and-templating)):

```
{% include book.ref_doc_readme %}
```

#### 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` ([Download GitBook.gitignore](https://github.com/github/gitignore/blob/master/GitBook.gitignore)).

#### 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](https://github.com/GitbookIO/plugin-autocover).

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

#### AsciiDoc

Since version 2.0.0, AsciiDoc can be used instead of Markdown, simply replace the `.md` by the `.adoc` extension. Chapters in the summary are detected from an ordered list in the `SUMMARY.adoc`.

## Publish your book

The platform [GitBook.com](https://www.gitbook.com/) 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 be used to extend your book's functionality. Read [GitbookIO/plugin](https://github.com/GitbookIO/plugin) for more information about how to build a plugin for GitBook.

Plugins needed to build a book can be installed using: `gitbook install ./`. You can find plugins at [plugins.gitbook.com](http://plugins.gitbook.com).


## Debugging

You can use the options `--log=debug` and `--debug` to get better error messages (with stack trace). For example:

```
$ gitbook build ./ --log=debug --debug
```

#### How to use the latest commit from GitBook in gitbook-cli

To use the latest commit from `GitBook/gitbook` with `gitbook-cli`:

```
$ git clone https://github.com/GitbookIO/gitbook.git ./gitbook
$ gitbook versions:link ./gitbook
```

Now `gitbook-cli` will be using the `./gitbook` folder.

You can uninstall it using: `gitbook versions:uninstall latest`.

---
_Source: https://npm.io/package/gitbook · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._