GitBook on Windows - kntmr-blog

GitBook の導入手順などをメモ。基本的なところはドキュメントに書いてありますが。

前提

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 を使うことにしました。事前に以下の手順が必要になります。

Graphviz インストール
環境変数 GRAPHVIZ_DOT を設定 (dot.exe ファイルのパスを設定する)

また、手元の環境では、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 すると正しく日本語が出力されるようになります。

前提