Gitbook 環境 マイ・ベスト

まとまった量のドキュメントをファイルとして提出する機会があり、Gitbookで作成した。
その時に自分なりの 2019年 年初時点でのベスト環境を作ったのでそれについて記述する。

TL;DR

どんな環境かというと、こんなかんじ。

• Dockerで作る Gitbook 環境
• PlantUMLを使える
• PDFやEPUBでの出力もすぐできる

この環境を作るためのファイル群をリポジトリとして公開した。

Gitbook プロジェクトテンプレート

Gitbook環境を作るためのファイル一式を次のリポジトリで公開している。

HeRoMo/gitbook-template: A gitbook project template

以下に使い方を記述する。

初期化

Gitbookを新規に作成するには次のコマンドを実行する。

$ curl https://codeload.github.com/HeRoMo/gitbook-template/zip/master -O
$ unzip master
$ mv gitbook-template-master your-gitbook-name
$ cd your-gitbook-name
$ docker-compose run --rm gitbook init

実行すると gitbook-template-master/gitbook 以下に次のファイル群が作成される。

./gitbook
├── README.md      # `gitbook init`で作成されるイントロファイル
├── SUMMARY.md     # `gitbook init`で作成される目次ファイル
├── book.json      # おすすめのGitbookプラグインの設定を含むコンフィグファイル。
└── node_modules/  # Dockerコンテナ内で別のボリュームがマウントされるので空となる

まあ、標準的な Gitbookのファイル構成かと思う。
とにかく、このgitbookディレクトリの中を自らの著作として編集すればよい。

book.json のtitleは自分のgitbookのタイトルを設定すると出力に反映される。その他の設定もConfiguration · GitBook Toolchain Documentationなどを参考に必要に応じて設定できる。

もし、既存のGitbookをこのテンプレートの仕組みで管理したい場合には、gitbookディレクトリに配置すればよい。

ローカルサーバの起動

次のコマンドでローカルのGitbookサーバが起動する。

$ docker-compose up

# 〜中略〜
gitbook_1   | Starting server ...
gitbook_1   | Serving book on http://localhost:4000

ローカルサーバが起動すると、表示されるメッセージの通り、http://localhost:4000でアクセスできる。

LiveReloadをインストールした Chrome ブラウザでアクセスすると、ファイルを更新するたびにブラウザがリロードして反映される¹。

book.jsonにプラグインを追加したときには、再起動するとサーバ起動前にインストールされる。

PlantUMLサポート

このGitbookテンプレートではPlantUMLをサポートしている。

```puml
@startuml
Bob -> Alice: hello
@enduml
```

上記が次の様にレンダリングされる²。

初期化時に生成する book.jsonに plantuml-cloudプラグインを設定している。これとdocker-composeで起動するbitjourney/plantuml-serviceによって、PlantUMLのレンダリングを行っている。
PlantUMLサーバが常に起動しているので他のPlantUMLのGitbookプラグインより速く快適にレンダリングできると思う。

PDF、EPUB、MOBIへの出力

各種電子ブック系ファイルへの出力も簡単にできるようにしている。

$ docker-compose run --rm gitbook pdf  # PDFファイル（book.pdf）を出力する
$ docker-compose run --rm gitbook epub # EPUBファイル(book.epub)を出力する
$ docker-compose run --rm gitbook mobi # mobi(kindle向け)ファイル(book.mobi)を出力する

いずれも gitbook ディレクトリに出力される。

使い方の説明は以上。

以下はオプショナルな内容なので、忙しい方は読み飛ばしてもらって構わない。

エディタ

エディタは自分の手に馴染んだ使いやすいものが一番であるのは言うまでもない。
私の場合、それはVSCodeで、以下の理由でおすすめである。

1. Markdown のための機能、拡張が充実している。
2. タスク設定が便利

Markdown のための機能、プラグインが充実している。

Markdown を書くためにおすすめの拡張をいくつか紹介する。

• Markdown Preview Enhanced
  • PlantUMLもさくさくレンダリングできる高機能プレビュー拡張³。はじめからMarkdownプレビューはバンドルされているけれど、こちらの方が何かと高機能。
• Markdown All in One
  • Markdownを書くのに便利なエディタ機能を追加する拡張
• vscode-textlint
  • Markdown用というわけではないが、文章の校正を強力にサポートしてくれる

そして、これらのプラグインを推奨に設定してリポジトリに含めておくことができるのも便利だ。
前述のGitbookテンプレートでもいくつか設定している。

タスク設定が便利

「ローカルサーバの起動」、「PDFファイルの出力」などよく使うコマンドをタスクとして登録しておける。
登録タスクはコマンドパレットから実行でき、細かな引数などを含めて登録しておけば、覚えておく必要性から解放される。

エディタグローバルな設定ではなく、プロジェクトごとに設定できるのがとてもよい。
前述のGitbookテンプレートにもいくつか登録している。

Task Runnerをインストールすると、リストをクリックするだけタスクを実行できるようになり、更に便利。

Gitリポジトリ

執筆中にはパブリックにしたくない場合もあると思う。Github でもプライベートリポジトリが作り放題になったのでGithubでいいじゃないかというところかもしれないが、Gitlabもなかなかおすすめ。

おすすめの理由は次の２点。

1. 統合されたCIパイプライン
2. 統合されたWebIDE

統合されたCIパイプライン

次のような.gitlab-ci.ymlファイルをプロジェクトのルートに置いておけば、masterにプッシュするたびに自動的にPDFファイルを生成できる。Github＋CircleCIでも同じことができるのだけど、複数のサービスで設定したりせずファイル一つ作るだけでできてしまうのは便利。

image: docker:latest

services:
  - docker:dind

before_script:
  - docker info
  - apk update
  - apk upgrade
  - apk add python python-dev py-pip build-base
  - pip install docker-compose

build:
  stage: build
  script:
    - docker-compose run --rm gitbook pdf
    - mkdir -p artifacts
    - mv gitbook/book.pdf artifacts/
  artifacts:
    name: "book"
    paths:
      - artifacts/
  only:
    - master

重たい処理をさせる場合には自前でRunnerを用意したほうが良いのだろうが、GitbookのPDFを出力する程度なら、用意されている共有環境で十分だと思う。
ドキュメントの提出先の担当者がエンジニアでない場合には、先方が開くことができる形式にする必要がある。ちょっとしたことだけどリポジトリにプッシュしたら自動的に生成されるのは便利だ。

統合されたWebIDE

基本的にはローカルにチェックアウトして編集するのだけど、リポジトリのWeb上でちょっと編集できると何かと便利。

Github上でもWeb上でファイルを編集することはできる。
が、あまり便利な機能とは言えないと思う。

GitlabではWebIDE機能が提供されており、より編集しやすくなっている。