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 を利用している方は、
nodebrew のインストールは、上記の Github に記述されているインストール方法ではなく
$ brew install nodebrew
でインストールできます。
MS-Windows
Microsoft Windows を利用している方は、
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設計ツール を配置した例を用意しました。参考にしてください。