GitBookはMarkdownで記述しGitで管理しているドキュメントを、簡単にHTMLやPDF、EPUB、MOBIなどで公開できるサービスです。今回はこのGitBookで使われているgitbookコマンドを用いて、Ubuntu上でドキュメントを生成する方法を紹介します。
今風な文書執筆・公開環境としてのGitBook
人類の進化は文書の作成と共にあります。より良い文書の存在が、質の高い教育、確実な情報の伝達、技術や文化の進歩を導いてきました。本連載が掲載されているgihyo.jpでも、今年の新春特別企画に「ドキュメントの構造化による、良いドキュメントの作成方法 」が掲載され注目を集めているように、いかにより良い文書をよりお手軽に作成できないか苦心されている方も多いことでしょう。
今回紹介する「GitBook 」は、技術者であれば使っている人が多いであろう「Git」と「Markdown」を使って、一つのソースからHTMLやPDF、EPUBなど複数の形式の文書・書籍を作成できるサービスです[1] 。さらに作成した文書はそのままGitBook上に公開できますし、オンラインでも編集できます。料金を払えばGitHubのようにプライベートリポジトリを作成することも可能です。また作成した書籍のGumroad経由での販売にも対応しています。
[1] ちなみにMarkdownだけでなくAsciiDocにも対応しています。数式にはTeXの書式を記述できますし、RmarkdownなドキュメントをGitBookで利用できるRgitbookなんてツールも存在します。
またGitBookはNode.jsベースで作成されており、そのツールキットはGitHub上で公開されています 。これを使えば、ローカルの環境でGitBookのようにMarkdownから各種形式の文書を生成したり、ウェブサーバーとして公開できるのです。
オンライン版のGitBook
GitBookでできることを把握するためには、オンライン版のGitBookを試すのが一番手っ取り早いでしょう。GitBookのサイト にアクセスし、アカウントを作成してください。GitHubのアカウントを使うこともできます。アカウントを作ったら「Create or Import your first book」ボタンから最初の文書を作成します。
図1 ドキュメントの作成画面
文書のテンプレートとして、「 Basic」「 Science」「 GitHub」「 Import」などから選べます。いずれもただのテンプレートで、あとから設定などで同様の機能を実現できるため最初は「Basic」を選びましょう。次に「Start Writing」を選択するとウェブ版のMarkdownエディターが起動しますので、あとはMarkdownをガリガリと書いていくだけです。このエディターはツールバーやファイルツリーだけでなく、目次やビルド結果のプレビューなども備えた 十分に高機能なエディターです。日本語にも対応しているため、単純な編集であればこれだけでも問題ないでしょう[2] 。
図2 一応日本語にも対応しているMarkdownエディター
編集が終わったら左上の「Save」ボタンを押してから、その隣の「戻る」ボタンで書籍のフロントページに戻りましょう。無事にドキュメントが生成されたら「Read」ボタンや各種フォーマットのドキュメントへのリンクが作成されているはずです。
図3 HTML版はこのように表示される
作成した文書はGitBookサーバー上のgitリポジトリとして保存されます。よってgitコマンドで文書をcloneすることも可能です。ただしcloneしたい場合は、GitBookの設定画面からパスワードを設定しておく必要があります。リポジトリのURLは文書毎の設定画面を確認してください。
作成した文書をGitHubにエクスポートすることも可能ですし、逆にGitHub上の文書をGitBookで ビルドして公開することも可能です。このあたりの詳しいことは「GitBookのヘルプ 」を参照してください。
UbuntuにおけるNode.jsとnpm
GitBookはNode.jsを使って作られたソフトウェアです。よってUbuntu上でローカルに使うためには、Node.jsを導入する必要があります。
Node.jsはとてもリリースペースの速いソフトウェアです。いろいろあってここ1年ぐらいで速くなりました。Ubuntu 14.04 LTSの公式リポジトリにはリリースがはやくなる前の0.10.25がパッケージ化されています[3] 。またnpmのパッケージも1.3.10と古いバージョンになっています。このためNodeパッケージによっては、より新しいNode.jsやnpmを要求するようなNodeパッケージは動かない可能性があります。そこでまずはUbuntuで、より新しいバージョンのNode.jsやnpmをインストールする方法を説明します。
[3] ちなみにNode.jsの4.xはLTSとなり、2015年のから2年半サポートされるようです。よって4.2.xが公式リポジトリに存在するUbuntu 16.04 LTSであれば、リポジトリからパッケージをインストールするだけで良いかもしれません。
Node.jsのバイナリパッケージは「Node.jsのリポジトリ 」から入手可能です。この方法で導入するリポジトリには、amd64やi386だけでなくarmhf向けバイナリパッケージも存在するため、Raspberry Pi 2上にインストールしたUbuntuでも利用できます。
ドキュメントの手順に従えば、以下の方法でNode.jsの4.x系のリポジトリを導入できます。
$ curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
$ sudo apt-get install -y nodejs
ここでダウンロードしている「setup_4.x 」は、実行中のディストリビューションを判定して、適切なリポジトリのスイートを選択し、リポジトリの鍵とURLを登録しているだけです。ダウンロードしたファイルをいきなり実行するのが不安であれば、ダウンロードして正しいファイルかや何を実行しているかといった内容を確認してから実行する形でももちろんかまいません[4] 。もしくは以下のように手動でリポジトリを登録した上で、nodejsパッケージをインストールしても良いでしょう。
$ curl -s https://deb.nodesource.com/gpgkey/nodesource.gpg.key \
| sudo apt-key add -
$ echo 'deb https://deb.nodesource.com/node_4.x trusty main' \
| sudo tee -a /etc/apt/sources.list.d/nodesource.list
$ echo 'deb-src https://deb.nodesource.com/node_4.x trusty main' \
| sudo tee -a /etc/apt/sources.list.d/nodesource.list
$ sudo apt-get update
$ sudo apt-get install nodejs
$ node -v
v4.2.6
Ubuntu 14.04 LTS以外を使う場合は、上記の2箇所の「trusty」を各リリースのコードネームに変更してください。「 lsb_release -cs」コマンドで確認できます。
Node.jsリポジトリにあるnodejsパッケージは、インストール後に実行されるスクリプト ( /var/lib/dpkg/info/nodejs.postinst)で以下のようなコマンドを実行しています。
update-alternatives --quiet --install /usr/bin/node node \
/usr/bin/nodejs 50 \
--slave /usr/share/man/man1/node.1.gz node.1.gz \
/usr/share/man/man1/nodejs.1.gz
このため「nodejs」コマンドだけでなく「node」コマンドでもNode.jsが実行されます。
Node.jsをインストールするとNode.jsのパッケージマネージャーであるnpmもついてきます。
$ npm -v
2.14.12
npmはnpmコマンドで更新できます。ただし、今は更新すると2.xから3.xにアップグレードされてしまうので、2.xが必要な場合は更新しないでおきましょう。
$ sudo npm install npm -g
/usr/bin/npm -> /usr/lib/node_modules/npm/bin/npm-cli.js
npm@3.5.3 /usr/lib/node_modules/npm
$ npm -v
3.5.3
グローバルオプション(-g)を付けたときのnpmのインストール先は「/usr/lib/node_modules」になっているので、sudoが必要です。このインストール先のプレフィックス(/usr)はnpm configコマンドで変更できます 。
GitBookのインストールと最初のテスト
GitBookはnpmコマンドでインストールします。これもグローバルオプション付きでインストールしておいたほうが、実行パスが通るので何かと便利でしょう。
$ sudo npm install gitbook-cli -g
$ gitbook --version
1.0.1
$ gitbook install
ちなみにインストールしているのはコマンドのフロントエンドである「gitbook-cli 」のほうです。gitbook-cliで提供されるgitbookコマンドが、「 gitbook install」でインストールされたGitBook本体である「gitbook 」を呼び出します。
では、さっそくgitbookコマンドを使って文書を作成してみましょう。
$ mkdir firstBook && cd $_
$ gitbook init
info: init book at /home/ubuntu/firstBook
info: detect structure from SUMMARY (if it exists)
info: create SUMMARY.md
info: create README.md
info: initialization is finished
Done, without error
$ ls
README.md SUMMARY.md
このディレクトリはまだGitリポジトリではありませんので、"git init"もしておきます。ついでに「GitBook用の.gitignore 」も取り込んでしまいましょう。
$ curl -L https://raw.githubusercontent.com/github/gitignore/master/GitBook.gitignore -o .gitignore
$ git init
Initialized empty Git repository in /home/ubuntu/firstBook/.git/
$ git add .
$ git commit -m "Initial commit"
[master (root-commit) 96da69a] Initial commit
3 files changed, 18 insertions(+)
create mode 100644 .gitignore
create mode 100644 README.md
create mode 100644 SUMMARY.md
今回はこのまま変更せずにHTMLを生成してみます。
$ gitbook build
info: loading book configuration....OK
info: load plugin gitbook-plugin-highlight ....OK
info: load plugin gitbook-plugin-search ....OK
info: load plugin gitbook-plugin-sharing ....OK
info: load plugin gitbook-plugin-fontsettings ....OK
info: >> 4 plugins loaded
info: start generation with website generator
info: clean website generatorOK
info: generation is finished
Done, without error
生成された「_book/index.html」にアクセスしてみてください。期待通りの結果になりましたか?
GitBookサービスのように、ファイルの変更とともにHTMLドキュメントが自動生成されるウェブサーバーとして動かしたいのであれば、serveサブコマンドを利用します。
$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...
(中略)
Starting server ...
Serving book on http://localhost:4000
この状態でドキュメントのソースを変更すると、自動的に再ビルドが行われ、ウェブブラウザのほうもJavaScriptが動く環境であれば自動的にドキュメントを再読み込みします。
PDF/EPUB/MOBIの生成
PDFやEPUB、MOBIを生成するためには、Calibreのebook-convertコマンドが必要です。さらにebook-convertコマンドを実行するためにはXサーバーが必要です。よってcalibreパッケージと、さらにもしXサーバーが動いていない環境でebook-convertを動かしたい場合は、xvfbパッケージもインストールしましょう。
また日本語PDFを生成するためにはpoppler-dataと日本語フォントが必要になります。
$ sudo apt-get install calibre xvfb poppler-data \
fonts-takao-pgothic fonts-takao-mincho
$ sudo tee /usr/local/bin/ebook-convert <<EOF
#!/bin/bash
xvfb-run /usr/bin/ebook-convert "\$@"
jOF
$ sudo chmod +x /usr/local/bin/ebook-convert
$ which ebook-convert
/usr/local/bin/ebook-convert
上記ではebook-convertをXvfb経由で実行するために、/usr/local/binにラッパーコマンドを追加しています。これでGitBook内部からebook-convertを呼んだ時にXvfbが動くことになります。
では、PDFやEPUB、MOBIを生成してみます。
$ gitbook pdf
(中略)
info: start generation with pdf generator
info: clean pdf generatorOK
info: write SUMMARY.html
info: start conversion to pdf ....OK
info: generation is finished
info: >> 1 file(s) generated
Done, without error
$ gitbook epub
(中略)
info: start generation with epub generator
info: clean epub generatorOK
info: write SUMMARY.html
info: start conversion to epub ....OK
info: generation is finished
info: >> 1 file(s) generated
Done, without error
$ gitbook mobi
(中略)
info: start generation with mobi generator
info: clean mobi generatorOK
info: write SUMMARY.html
info: start conversion to mobi ....OK
info: generation is finished
info: >> 1 file(s) generated
Done, without error
$ ls
_book book.epub book.mobi book.pdf README.md SUMMARY.md
生成されたそれぞれのファイルが、正しく表示されることを確認しておきましょう。
なおUbuntu 14.04 LTSの公式リポジトリにあるCalibre 1.25.0の場合、生成されるEPUBファイルのバージョンは2.0となります。
GitBookの書き方
ドキュメントの作成方法はわかりましたので、あとはMarkdownを書くだけです。Markdownの記述自体はどんなエディターを使ってもかまわないので、Ubuntuで使えるMarkdownエディターについてまとまっている第389回 や第390回 が参考になるでしょう。
GitBookヘルプのMarkdown記法 にもあるように、GitHub Flavored Markdownベースになっています。またテンプレート機能 やファイルの書式毎のスタイルの設定 もできますので、比較的自由にデザインできそうです。JSONで記述する設定ファイル には文書のメタデータや 利用するプラグインのリストを記述します。また多言語化 にも対応しています。
ドキュメントのサンプルはGitBookを検索するのはもちろんのこと、GitBookのヘルプ自体のソースコード も参考になることでしょう。
GitBookは日本語の基本的な対応や縦書き・ルビなど、既存の電子書籍生成ツールと比べるとまだまだ弱い部分がたくさん存在します。しかしながらGitHubとの親和性の高さや、Markdownを書けばいろいろなフォーマットが生成できること、何より生成したドキュメントを公開できる基盤が存在することから、今後もさまざまなソフトウェアのドキュメントがGitBookで公開されるようになるものと思います。