gitbookを使ってドキュメントを生成する

2019-06-05約 10 分

概要

GitBookを使ってドキュメントを生成するまでをやってみました。なお、この記事で紹介しているのはgitbook-cliであり、クラウドサービスのGitBookはこちら↓を見て下さい。

https://www.gitbook.com/

どんなものができるのか

こんなドキュメントが作れます。

デフォルトのデザインだとこんなドキュメントが作れます。

↓ ※このサイトをキャプチャしています。

https://gitbookio.gitbooks.io/documentation/index.html

検証した環境

macOS mojava
nodejs 12.1.0
npm 6.9.0

nodejs npm の紹介&導入は省きます。

gitbookのインストール

npmを使ってgitbook-cliをインストールします。コマンドを実行すると以下のようなメッセージが出てきます。

$ npm install -g gitbook-cli
/usr/local/bin/gitbook -> /usr/local/lib/node_modules/gitbook-cli/bin/gitbook.js
+ gitbook-cli@2.3.2
added 578 packages from 672 contributors in 18.22s

これを導入することによりgitbookコマンドが使えるようになります。

こちらのバージョンがインストールされました。

$ gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3

プロジェクトの作成

プロジェクトを作成していきます。任意のディレクトリでgitbookコマンドを叩きます。

$ mkdir gitbook_test
$ cd gitbook_test
$ gitbook init

すると REAME.md と SUMMARY.md が作成されます。

$ tree ../gitbook_test 
../gitbook_test
├── README.md
└── SUMMARY.md

ディレクトリ構成について

基本的なディレクトリ構成について紹介します。

.
├── README.md   # 概要を書く
├── SUMMARY.md   # 目次を書く
├── _book   # ビルドしたファイルが置かれるディレクトリ
├── book.json   # 設定を記述するファイル
├── docs   # マークダウンファイルを配置するディレクトリ
└── img   # マークダウンで利用する画像を配置するディレクトリ

README.md, SUMMARY.md 以外は自分で作成します。 docs や img のディレクトリ名は固定ではなく任意の名前にすることが出来ました。

ドキュメントの記述

概要とコンテンツが1ページある簡単なドキュメントを生成してみます。

docs以下にhello.mdを作成します。 imgに適当な画像を置き、 docs/hello.md

# Hello World

- 最初の投稿

![](/img/test.png)

このマークダウンではimgに配置した画像を参照しています。このソースではルートパスで参照していますが、ビルド時には相対パスに変換されます。なので、Webサーバのサブディレクトリに配置した場合でも正しく参照してくれるハズです。

README.md

# Introduction

- 概要のページです

test

※デフォルトではIntroductionとだけ記述がありますが、中身はなんでも良いです。

SUMMARY.md

# 概要

[Introduction](./README.md)

[Hello World!](./docs/hello.md)

日本語化

book.jsonに次のよう記述します。 book.json

{
  "language": "ja"
}

ビルドインサーバの起動

gitbookのルートディレクトリに移動し、gitbook serveでビルドインサーバを起動することが出来ます。

gitbook serve 
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 2 pages 
info: found 0 asset files 
info: >> generation finished with success in 0.7s ! 

Starting server ...
Serving book on http://localhost:4000

http://localhost:4000にアクセスするとマークダウンから生成されたhtmlファイルを見ることができます。ドキュメントを更新すると変更を検知して自動でリロードしてくれる嬉しい機能がついてます。

ビルドとHTMLの生成

以下のコマンドでビルドすることができます。実行すると次のようになります。

$ gitbook build
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 2 pages 
info: found 1 asset files 
info: >> generation finished with success in 0.6s !

ビルドされたファイルは_bookの中に吐かれます。

(例)

_book
├── docs
│   └── hello.html
├── gitbook
│   ├── fonts
│   │   └── fontawesome
│   │       ├── FontAwesome.otf
│   │       ├── fontawesome-webfont.eot
│   │       ├── fontawesome-webfont.svg
│   │       ├── fontawesome-webfont.ttf
│   │       ├── fontawesome-webfont.woff
│   │       └── fontawesome-webfont.woff2
│   ├── gitbook-plugin-fontsettings
│   │   ├── fontsettings.js
│   │   └── website.css
│   ├── gitbook-plugin-highlight
│   │   ├── ebook.css
│   │   └── website.css
│   ├── gitbook-plugin-lunr
│   │   ├── lunr.min.js
│   │   └── search-lunr.js
│   ├── gitbook-plugin-search
│   │   ├── lunr.min.js
│   │   ├── search-engine.js
│   │   ├── search.css
│   │   └── search.js
│   ├── gitbook-plugin-sharing
│   │   └── buttons.js
│   ├── gitbook.js
│   ├── images
│   │   ├── apple-touch-icon-precomposed-152.png
│   │   └── favicon.ico
│   ├── style.css
│   └── theme.js
├── img
│   └── test.png
├── index.html
└── search_index.json

PDFの生成

PDFの生成にはCalibreが必要です。

https://calibre-ebook.com

mac (homebrew) の場合はbrew cask install Calibreで取得することができます。

$ gitbook pdf              
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 2 pages 
info: found 1 asset files 
info: >> generation finished with success in 5.5s ! 
info: >> 1 file(s) generated