GitBook で環境毎の変数を扱う

GitBook とは Sphinx などと同じように Markdown で書かれたドキュメントを綺麗な見た目で PDF や eBook 形式に変換してくれるツールです。今回は GitBook のドキュメント内で変数を扱う際に、 NODE_ENV など環境によってその変数の値を変えたい場合のやり方について紹介します。

そもそも GitBook にはドキュメントのルートディレクトリに book.js という名前の JavaScript ファイルを置くことで build や serve 時に動的な処理を挟み込む仕組みがあります。book.js 内で自前で書いてしまってもいいのですが、今回は Node ライブラリを組み合わせることで手間をかけずに実現したいと思います。

ライブラリのインストール

node-config をインストールします。

$ cd /path/to/doc_root
$ npm install conifg

本来は package.json を使って依存を管理しますが、そのあたりのセットアップから始めると長くなってしまうので、ここでは簡単にインストールします。

設定ファイルの準備

node-config はいろいろなやり方をサポートしているのでかならずしもこの手順でないとダメなわけではないです。詳細は node-config のドキュメントでも読んでみてください。

まず、基本的な設定は default.json というファイルで管理します。

$ cd /path/to/doc_root
$ mkdir config
$ vi config/default.json

default.json

{
  "variables": {
    "key": "value",
    "hello": "world"
  }
}

環境毎の設定は <環境名>.json という名前で作成します。

$ vi config/test.json

test.json

{
  "variables": {
    "key": "value",
    "hello": "gitbook"
  }
}

このとき、 default.json と被っている要素については環境毎の内容で上書きされます。こうすることで重複して管理しなくてもよくなります。

$ ls -l config
total 8
-rw-r--r-- 1 hiyosi staff 66 12 15 15:03 default.json
-rw-r--r-- 1 hiyosi staff 68 12 15 15:03 test.json

最後にこれらの設定ファイルを node-config を使って読み込むような book.js を準備します。

$ vi book.js

book.js

var conf = require('config');

module.exports = conf;

ビルド

環境名はビルド時に NODE_ENV の値を見るので、export するなり、ビルド時に渡すなりしてあげればよいです。

$ export NODE_ENV=test
$ gitbook build

$ NODE_ENV=test gitbook build

ちなみに、後者のように都度環境変数を渡す場合においては gitbook serve を実行する際にも環境変数を渡す必要があることに注意が必要です(sserveするとビルドが走るため)

変数の呼び出し

読み込んだ JSON　ファイルの内容は book.json で扱っていたときと同様に book 変数からたどることができます。
https://toolchain.gitbook.com/templating/variables.html

book.[CONFIGURATION_DATA]

先ほど設定した内容だと、テンプレート内からは以下のように呼び出すことができます。

{{ book.hello }} // ビルドすると環境変数の値により world または gitbook が出力される

まとめ

NODE_ENV と node-config を使って GitBook 内で簡単に環境毎の変数を手軽に扱う方法を紹介しました。仕事などで使う場合には、ある箇所は公開する際に隠したいという要望や、ドキュメント内の URL を環境毎に変更したいといった要望が出てくると思います。それ毎にドキュメントを分けたり条件分岐したりもいいのですが、今回のような方法を使うことですっきりと管理できると思いますので、よければ使ってみてください。

P.S.

GitBook とは関係ないですが、Sphinx で Markdown を変換する方法も試してみたところテーブルが崩れてしまったのが残念でした・・・ (recommonmark のせい？)