gitbookを使って技術書を書くための環境を構築する手順をまとめたいと思います。

gitbookとは、Node.jsで動く、
チームでドキュメントを作って、オンライン上で公開するためのツールです。
markdownで書いたドキュメントをhtmlやpdfなどに体裁を整えて変換することができます。

このエントリでは、以下の4点について、順を追って手順を示していきます。

  • gitbookの執筆環境構築
  • textlintによる自動チェック
  • html,pdf,epub形式での書籍の出力
  • githubでの執筆環境の管理

gitbookの執筆環境構築

まずは、gitbookの執筆環境を作ります。
以下の、gitbookのnodeのモジュールをインストールします。

gitbook | npmjs.com
https://www.npmjs.com/package/gitbook

gitbookのインストール

以下コマンドのように、作成する書籍用の作業ディレクトリを作成します。

$ mkdir gitbook-sample && cd $_

ndenvがインストールされている前提ですが、
以下のようにして使用するnodejsのバージョンを指定します。 (ここではv7.5.0を指定)

$ ndenv local v7.5.0

npmのパッケージ管理用にリポジトリを初期化します。

$ npm init

以下のコマンドでgitbookをインストールします。

$ npm install --save-dev gitbook-cli

gitbookの初期化

書籍用のディレクトリ配下を、gitbook用に初期化します。

$ node_modules/.bin/gitbook init

※フルパス入力が面倒であれば「export PATH=$PATH:./node_modules/.bin」のように事前にパスを通しておきます。

gitbookでの執筆

以下のコマンドでgitbook-serverを起動します。

$ node_modules/.bin/gitbook serve

しばらくすると、以下のように表示されるので、表示されたURLをブラウザで開きます。

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

作業用ディレクトリ配下のファイルを編集・保存すると、ブラウザのビューが更新されます。

Markdownの文法がわからなければ、以下のチートシートなどを参考にしてください。

Markdown Cheatsheet | adam-p/markdown-here
https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

textlintによる自動チェック

次に、textlintをセットアップし、
ルールに従って文書が記載されているかを自動でチェックできるようにします。

textlint
https://github.com/textlint/textlint

textlintのインストール

以下のコマンドでtextlintと、IT技術用語統一ルールをインストールします。

$ npm install --save-dev textlint textlint-rule-spellcheck-tech-word

IT技術用語統一ルールについては、以下を参照してください。
https://github.com/azu/textlint-rule-spellcheck-tech-word

ルールの定義とtextlintの実行

以下のように「.textlintrc」を作成して、IT技術用語統一ルールを有効にします。

.textlintrc

{
  "rules": {
    "spellcheck-tech-word": true
  }
}

以下のコマンドでtextlintを実行し、自動チェックを実行します。

$ node_modules/.bin/textlint *.md

gulpによるファイル監視とtextlintの実行

次に、gulpを使って、
ファイルの変更を監視して、textlintを実行するように設定します。
以下のコマンドでgulp, gulp-textlintをインストールします。

$ npm install --save-dev gulp gulp-textlint

以下のように「gulpfile.js」を作成して、mdファイルを監視し、texlintを実行するようにします。

gulpfile.js

var gulp = require('gulp');
var textlint = require('gulp-textlint');

gulp.task('textlint', function(){
  return gulp.src(['./**/*.md', '!node_modules/**/*'])
    .pipe(textlint());
});

gulp.task('watch', ['textlint'], function(){
  gulp.watch('./**/*.md', ['textlint']);
});

以下のコマンドで、mdファイルの監視を開始します。

$ node_modules/.bin/gulp watch

html,pdf形式での書籍の出力

次に、文書をhtml及びpdf形式で出力する環境を設定します。

html形式での書籍の出力

以下のコマンドを実行すると、gitbookのHTMLが_book配下に生成出来ます。

$ ./node_modules/.bin/gitbook build

pdf形式での書籍の出力

PDF・epubファイルを生成する為に、
以下のサイトを参照してcalibreをインストールします。
※linux環境であることが前提です。

Download for linux | Calire
http://calibre-ebook.com/download_linux

「Binary install」というところにコマンドが書いてあるので、それをコピー&ペーストして実行します。

日本語が含まれるレポートを作る場合は、
以下のコマンドで、IPAフォントをインストールします。
※以下のコマンドは、CentOS環境であることが前提です。

$ sudo yum install ipa-gothic-fonts ipa-mincho-fonts ipa-pgothic-fonts ipa-pmincho-fonts

ここまでの準備を行った上で、
以下のコマンドを実行するとPDF形式で書籍を生成することが出来ます。

$ node_modules/.bin/gitbook pdf ./ book.pdf

githubでの執筆環境の管理

最後に、ここで作成したリポジトリを、
githubで共有し、チームでドキュメント制作ができるようにします。

gitignoreの準備

以下を参考に「.gitignore」を作成します。

GitBook.gitignore | github/gitignore
https://github.com/github/gitignore/blob/master/GitBook.gitignore

リポジトリの準備とpush

以下のように、作成したリポジトリをgithubにpushします。

$ git init
$ git add .
$ git commit -a -m "initial commit"
$ git remote add origin ※githubリポジトリのパス※
$ git push -u origin master

circleciによるtextlintの実行

circleciでtextlintを実行する場合は、以下のようなファイルを追加しておきます。

circle.yml

test:
  override:
    - node_modules/.bin/gulp textlint

このようにCIを設定した状態にした上で、
ドキュメントの変更承認をpullreqベースで行えば、
自動チェックと、第三者レビューが同時に出来るので、フローを回しやすいと思います。

参考サイト

このエントリをまとめるにあたって、以下のサイトを参考にしました。

書籍執筆でお世話になったツール 〜Re:VIEW, textlint, prh, goemon, GitHub, CircleCI〜
http://orangain.hatenablog.com/entry/writing-tools

textlintで日本語の文章をチェックする | Web Scratch
http://efcl.info/2015/09/10/introduce-textlint/

WEB+DB PRESS用語統一ルール
https://github.com/azu/textlint-rule-web-plus-db

第406回 Node.js製のGitBookでお手軽に電子書籍作成 | gihyo.jp http://gihyo.jp/admin/serial/01/ubuntu-recipe/0406?page=2

技術文書をソフトウェア開発する話
https://azu.gitbooks.io/nodefest-technical-writing/content/

[unofficial] WEB+DB PRESS用語統一ルール for textlint
https://github.com/azu/textlint-rule-web-plus-db

inao/WEB+DB PRESS用語統一ルール
https://gist.github.com/inao/f55e8232e150aee918b9