description: Let's start documentation with gitbook-cli.

gitbookの使い方

手軽に記述できる Markdown形式を利用して各種の文章を作成できる gitbook-cli の使い方を紹介します。後半では PlantUML を利用して UML を文章内に組み込む方法も記述しています。

github で公開している how-to-gitbook の Readme.jp.md の ~~丸々コピーです~~ GitBook V2になり、最初に書いた頃と、参照先のサイトが消えてしまったので一部改定しました。

GitBook について

GitBook は、Markdown形式で作成した文章を HTML形式、PDF形式、ePub形式などの電子ブックを簡単に作ることができます。

about には、

GitBookは、開発者のドキュメント作成のためのオープンソースツールとして2014年半ばにスタートしました。
今日では、あらゆる規模のチームに対して、優れた内部と外部のドキュメントを構築する能力を強化しています。

と記述されています。

GitBook は、クラウドサービスですが、
gitbook-cli を利用して、スタンドアロンで生成する環境を構築できます。

GitBook の開発拠点は、フランスアルプスから 1時間ほどの美しい都市リヨンにあります。

準備

GitBook は NODE.js を利用したツールなので予め NODE.js を利用できる環境を整えてください。

NODE.js を直接インストールしても良いですが、利用するバージョンを簡単に切り替えらる仕組みを導入した方が便利です。

NODE.js 環境

macOS

macOS を利用している方は、

Homebrew をインストール
nodebrew をインストール

nodebrew のインストールは、上記の Github に記述されているインストール方法ではなく

$ brew install nodebrew

でインストールできます。

MS-Windows

Microsoft Windows を利用している方は、

Scoop をインストール
nvm をインストール

yarn のインストール

それから、npm の代わりに yarm をインストールしておきましょう。

macOS

$ brew install yarn

MS-Windows

> scoop install yarn

`gitbook-cli` のインストール

やっと本題です。

$ yarn global add gitbook-cli --prefix /usr/local

コマンドラインツールは、global に add するのがお約束です。
npm を利用している方は、つぎのコマンドを実行します。　

$ npm install --global gitbook-cli

確認

gitbook --help を実行し、つぎの様に表示されれば、gitbook-cli のインストールは成功しました。

$ gitbook --help

  Usage: gitbook [options] [command]


  Options:

    -v, --gitbook [version]  specify GitBook version to use
    -d, --debug              enable verbose error
    -V, --version            Display running versions of gitbook and gitbook-cli
    -h, --help               output usage information


  Commands:

    ls                        List versions installed locally
    current                   Display currently activated version
    ls-remote                 List remote versions available for install
    fetch [version]           Download and install a <version>
    alias [folder] [version]  Set an alias named <version> pointing to <folder>
    uninstall [version]       Uninstall a version
    update [tag]              Update to the latest version of GitBook
    help                      List commands for GitBook
    *                         run a command with a specific gitbook version

初期化

$ gitbook init directory

GitBook の詳しい使い方については、GitBook V1の「GitBook ツールチェーンドキュメント」サイトが消えてしまったので、GitHubから参照します。 GitBook docs を参照してください。

「GitBook ツールチェーンドキュメント」をローカルに復元する方法を下記に書いておきます。
GitHub: gitbook を clone するか fork & clone して docs ディレクトリで

$ yarn install
$ gitbook install
$ gitbook serve
...
Starting server ...
Serving book on http://localhost:4000

すれば、 http://localhost:4000 で閲覧できます。

プラグイン

GitBook は、プラグインを導入し機能拡張を実現できます。

GitBook のプラグインは、 GitBook Plugins サイトより検索できます。
しかし、ちょっと記述内容に、謝りがあったり、情報が足りなかったり、するものが多いです。
GitBook Version 2 になって、旧のサイトが消えてしまいました。

お勧めのプラグインは、

目次の折りたたみ
ページ目次
UMLの記述
favicon設定
LOGO画像設定

SUMMARYの折畳み

GitBook で作成するドキュメントには、画面の左側に目次が付きます。
長い文章になると目次項目が多くなり、折り畳みたくなりませんか？
この要求を満たすのが expand系のプラグインです。いくつか登録されていますが expand-active-chapter が良いと思います。

Book.json の plugins に追加します。

{
  "plugins": ["expand-active-chapter"]
}

インストールを行う。

$ gitbook install

ページにTOC

TOC(Table of contents)をページ上部に表示します。

Book.json の plugins に追加します。

{
  "plugins": ["navigator"],
}

インストールを行う。

$ gitbook install

UML

PlantUML を利用するとテキストエディタなどで UML の各種ダイアグラム＋ α の図を描けます。
GitBookでも、プラグインを導入すると、インラインまたは、別ファイルで作成した UMLをドキュメント内に配置できます。

GitBook Plugins の検索では、別のプラグインがヒットします。

このプラグインを使えば、book.json で、文字コード指定とフォーマット指定ができます。

先ず、NODEモジュール gitbook-plugin-uml をインストールします。

$ yarn add gitbook-plugin-uml

Book.json の plugins に追加します。

{
  "plugins": ["uml"],
  "pluginsConfig": {
    "uml": {
      "charset": "utf-8",
      "format": "svg"
    }
  }
}

インストールを行う。

$ gitbook install

favicon設定

GitBookの標準の favicon を変更するには、プラグインを利用します。
gitbook-plugin-custom-favicon を導入しました。

book.json の plugins に、つぎの様に記述します。

{
  "plugins": ["custom-favicon"],
  "pluginsConfig": {
    "favicon": "./assets/images/icon/favicon.ico"
  }
}

gitbook install でプラグインをインストールしてください。

LOGO画像設定

GitBook plugin:Insert logo を利用すると、左側のサマリーの上部にロゴ画像を挿入することが

book.json の plugins に、つぎの様に記述します。

{
  "plugins": [ "insert-logo"],
  "pluginsConfig": {
    "insert-logo": {
      "url": "/assets/images/mitsuhisaT_logo_L.png",
      "style": "background: none;"
    }
  }
}

gitbook install でプラグインをインストールしてください。

プラグインを纏めてインストール

個別に説明した、五種のプラグイン＋αを導入する場合の book.json はつぎの通りです。

  "plugins": [
    "custom-favicon",
    "insert-logo",
    "expand-active-chapter",
    "navigator",
    "uml"
  ],
  "pluginsConfig": {
    "favicon": "./assets/images/icon/favicon.ico",
    "insert-logo": {
      "url": "../assets/images/mitsuhisaT_logo_L.png",
      "style": "background: none;"
    },
    "sharing": {
      "facebook": false,
      "twitter": false,
      "google": true,
      "weibo": false,
      "instapaper": false,
      "vk": false,
      "all": [
        "facebook", "twitter", "google", "weibo", "instapaper", "vk"
      ]
    },
    "uml": {
      "charset": "utf-8",
      "format": "svg"
    }
  }

電子ブックとPDFの生成

gitbook-cli 単体では、ePub形式の電子ブックやPDF形式のファイルの生成はできません。
Generating eBooks and PDFs を参考に calibre をインストールします。
calibre は、無料で利用できる電子ブックの管理ツールです。

calibre is a powerful and easy to use e-book manager.
calibre は、強力で簡単に使える電子ブックマネージャーです。

さらに、UMLをSVG形式で出力しているので、ePub、PDFを生成するために
svgexport が必要になります。

calibreのインストール

ダウンロードサイトから、利用環境にあったインストーラーを選びダウンロードし、インストールを行います。

macOSの追加設定

ebook-convert のシンボリックリンクを作ります。Generating eBooks and PDFs に記述されている
/usr/bin には、生成できなかったので、 /usr/local/bin に作りました。

$ sudo ln -s /Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin

svgexportのインストール

svgexportは、SVGファイルをPNGとJPEGにエクスポートするNODE.jsのモジュール、かつコマンドラインツールで、SVGファイルのレンダリングにPhantomJSを利用しています。

svgexport is a Node.js module and command-line tool for exporting SVG files to PNG and JPEG, it uses PhantomJS for rendering SVG files.

GitBookでePub、PDFを出力する場合は、コマンドラインツールとして利用するので、つぎのようにインストールします。　

$ yarn global add svgexport --prefix /usr/local

サンプル

github:gitbook Usage の sample ディレクトリに簡単な UML と GUI設計ツールを配置した例を用意しました。参考にしてください。