gitbookで技術書を書く環境の構築手順
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