GitBook の導入手順などをメモ。基本的なところはドキュメントに書いてありますが。
V2 changes - GitBook Documentation
前提
node と npm のバージョンは以下の通り。
> node -v v8.11.2 > npm -v 5.6.0
尚、手元の環境が Windows だからなのか、いろいろと思った通りに動作しないところがあります。が、GitHub の issue にワークアラウンドが載っています。一応、PR があるはずなんだけど、マージはされてないっぽい？開発があまり活発じゃないんだろうか...。
インストール
gitbook-cli をインストール。初回の gitbook 実行時にコマンドがインストールされます。
> npm install -g gitbook-cli > gitbook --version CLI version: 2.3.2 GitBook version: 3.2.3
プロジェクト作成
適当にプロジェクトフォルダを作成して初期化。
> mkdir sample > cd sample > gitbook init
プラグインインストール
今回は次のプラグインを使っています。
----- (2018/06/11 追記) -----
当初、gitbook-plugin-puml を使おうと思ってたのですが、gitbook-plugin-uml を使うことにしました。事前に以下の手順が必要になります。
また、手元の環境では、gitbook-plugin-uml のインストールでコケるので、git config --global url."https://".insteadOf git:// を実施。(パッケージをインストールしたら戻すこと)
(参考) https://stackoverflow.com/questions/31744852/npm-install-giving-error-while-accessing-git-url
----- (追記ここまで) -----
まずは、npm パッケージをインストール。
> npm install gitbook-plugin-uml > npm install gitbook-plugin-livereload
プロジェクトのルートに book.json を作成します。
{ "plugins": [ "-sharing", "uml", "livereload" ], "pluginsConfig": { "uml": { "charset" : "UTF-8" } } }
プラグインインストール。
> gitbook install
ビルド
以下のコマンドでビルドします。プロジェクトのルートに _book が生成されるので、これを Web サーバーにデプロイします。
※ Windows 環境ではエラーになることがあります。ワークアラウンドは下記参照。
> gitbook build
ローカルで確認する場合は以下のコマンドを実行します。ローカルでサーバーが起動して localhost:4000 にアクセスすると画面が表示されます。また、ローカルでファイルを編集するとライブリロードされます。
※ Windows 環境ではエラーになることがあります。ワークアラウンドは下記参照。
> gitbook serve
PDF 出力
PDF 出力には ebook-convert というコマンドが使われるようです。このコマンドを使えるようにするには Calibre をインストールします。
calibre - Download for Windows
以下のコマンドで PDF を出力します。
> gitbook pdf ./ hoge.pdf
HTML / PDF のスタイルを変更する
book.json を編集します。
{ "plugins": [ "-sharing", "uml", "livereload" ], "pluginsConfig": { "uml": { "charset" : "UTF-8" } }, "styles": { "website": "styles/website.css", "pdf": "styles/pdf.css" } }
新しく css ファイルを作成して、カスタマイズするスタイルを定義します。HTML は Chrome の開発者ツールで class などを特定できますが、PDF のスタイルはちょっと分かり辛いかも。おそらく以下がオリジナルのファイルなのでこれを参考にする。
~/.gitbook/versions/3.2.3/node_modules/gitbook-plugin-theme-default/_assets/ebook/pdf.css
ワークアラウンドをまとめます。
gitbook serve と gitbook build でエラーになる場合
~/.gitbook/versions/3.2.3/lib/output/website/copyPluginAssets.js を以下のように編集します。
return fs.copyDir( assetsFolder, assetOutputFolder, { deleteFirst: false, overwrite: true, confirm: true // これを false に書き換える } );
(参考) https://github.com/GitbookIO/gitbook/issues/1309#issuecomment-273584516
また、旧バージョンの gitbook ではエラーになりません。ただし、この方法だと検索機能が利用できなくなります。
旧バージョンをインストール。
> gitbook fetch 2.6.7 > gitbook -v 2.6.7
旧バージョンを指定してコマンドを実行。
> gitbook serve --gitbook=2.6.7 > gitbook build --gitbook=2.6.7
(参考) https://github.com/GitbookIO/gitbook/issues/1379#issuecomment-303628878
ライブリロードでエラーになる場合
Windows 環境ではライブリロード時にサーバーが停止することがあります。以下の手順で回避できます。
gitbook serveを実行_bookフォルダを削除する
以降、ファイル編集後、正常にサーバーが再起動してリロードされるようになります。
(参考) https://github.com/GitbookIO/gitbook/issues/1379#issuecomment-320579569
gitbook-plugin-puml で日本語が文字化ける場合
gitbook-plugin-puml で日本語を使うと文字化けして表示されます。これは、plantuml-encoder の 1.2.4 で修正されているようです。が、gitbook-plugin-puml の package.json が plantuml-encoder@1.2.3 になっています。(2018/06/08 時点では 1.2.5 が最新の模様)
(参考) https://github.com/markushedvall/plantuml-encoder/issues/4
<プロジェクトフォルダ>/node_modules/gitbook-plugin-puml/package.json を編集します。
"dependencies": { "plantuml-encoder": "1.2.3" // これを 1.2.5 に変更 },
<プロジェクトフォルダ>/node_modules/gitbook-plugin-puml/ でコマンドプロンプトを起動。
> npm install
これで gitbook build or gitbook serve すると正しく日本語が出力されるようになります。
