今までドキュメントは適当なMarkdownで書いてそれを適当にGitBookでウェブサイトに変換していた。だがGitBookはコマンドラインツールの開発をやめてしまっている。なのでGitBook公式のホスティングサービスに移行するか、何か代替品を探さなければならない。というわけで探しているのだが……。
- 既存のGitBook用ファイルを使いまわしたい
- 何に移行するにしても少しの手直しは必要になるのである程度は我慢。
- このためにAsciiDocとかLaTeXはとりあえず除外
- 数式が書ける
- これは（mathjax/katexの違いはあれど）大抵のものがクリアしている
- HTMLが出力できる
- 基本的に全てが対応している。
- PDFも出力できる
- 全然誰も興味がないらしい……誰も対応していない……。
- ヒントボックスとかが欲しい
- テンプレート機能があればなんとかなるが、あったほうが圧倒的に楽。
- 多言語対応（できれば）
- 最悪全言語生成して繋げばいいので優先度は低め。
- インストールが楽
- そんなソフトウェアはない。
GitBook v2
ホスティングサービスとして生まれ変わったGitBook。
Pros
- ホスティングサービス上でのサポートが超強力
- 強いエディタ、チーム管理、ロゴやデザインのカスタマイズ、etc
- GitHub、Slackなどの外部サービスとの連携が楽。
- GitBookの資産はほぼそのまま利用可能（当然）
Cons
- 多言語対応がなくなった
- PDFの出力をサポートしなくなった
- 関係ないけどAsciiDocサポートもなくなった
- 簡単なのは使えたから気づかなかったけど数式プラグインは移行途上らしい
- 手元で動かせないので向こうのサービスに完全に依存してしまう
mdBook
RustによるGitBook的ツール。発展途上感はある。
Pros
- 速い。ストレスフリー（大事）
- GitBookからの移行も楽
- cargoが入っていればインストールが結構楽
Cons
- 多言語対応なし
- 4年間（Issue番号一桁、2015年から）、多言語対応はどういう形でなされるべきか、そもそも必要かとの議論が続いている。
- ヒントボックスがない（自分で作れはするっぽい？）
- PDF出力が少し面倒（
mdbook-latexを使う？） - サイドバーの索引をfoldできない
- 本ならChapterの階層は深くならないのだろうが、設定の説明をカテゴリ別に分けてると見栄えが悪い……。
docsify
静的サイトジェネレータではなく、Markdownファイルを読み込んでその場でレンダリングするらしい。
Pros
- 多言語対応が簡単
- PDFを作るプラグインがあるっぽい
Cons
- 環境構築は（mdBookよりは）難しい
- PDFを作るプラグインの実行に失敗した
- のでPDFの見栄えがまだわからない
GitBook v1
能力的には最強だったのに開発が止まってしまった可哀想な子。
Pros
- PDFも出力可能、しかもPDFの見た目が綺麗
- 多言語対応あり、最初に言語を選ぶ形
- 多彩なヒントボックス、その他見栄えを整えるためのプラグインが多数。すぐ思いつくことは大抵できる。
Cons
- 実行速度が遅い
- 開発終了
まとめ
改めて見てみると、GitBook v1がハチャメチャに強かっただけだった。
GitBook v2はエンタープライズ向けWebサイトホスティングサービス的な方向に向かっている気がする。コラボレーションとかブランディングのような機能が強化され、ローカルでは使えなくなり、PDFやeBookへの出力や多言語対応は切られた。
mdBookは速度やインストールの手軽さを考えるとかなり良いが、やはりまだ機能が少ない。ヒントボックスなんかはプラグインとして作ればウケるかもしれない（探せばあるかもしれない）が、Web関係はほとんど触ったことがない分野なのでできるかどうかわからない。
docsifyが今のところ一番いい代替だろうか。PDFの見栄えがGitBook並みによければ、移行してもいいかもしれない。
GitBook v1、なぜ死んでしまったのか……。フォークしてnodejs勉強して自分でアップデートし続ければいいのかな。まあソフトウェアそのものでさえ手間がすごいのだから、ドキュメントにそこまでの手間はかけられないのだが。
追記
この記事を書いた後しばらくgitbookのためのDockerイメージを作ろうとしていたのだが、dependencyの複数が開発停止になっており、HTMLはかろうじて作れるものの、PDFはかなり詰んでいる。手間を考えると、やはりもうgitbookは捨てるしかなさそうだ。具体的には、svgexportが依存しているphantomjsが開発停止になっているし、mathjaxが近頃メジャーバージョンアップをしたせいでダウングレードしないと動かない。
かと言ってGitBook v2は目的に合わなさすぎて使えない。PDFを諦めてもいいのかもしれないが、そうなると静的サイトが生成されてほしいし、となるとmdbookしかない。mdbookの拡張機能について学ぶ必要があるだろう。あるいはdocsifyからPDFを生成できるようにちょっと頑張ってみるかだ。
docsifyでPDFを作ってみたが、gitbookと比較すると以下のような不満点がある。
- 目次が生成されない
- ページとファイルが対応しない
- ファイル内リンクが生成されない
- コードブロックの背景が出力されない
思いっきり頑張って設定してみれば解決するのかもしれないが、プラグインに頼らずgitbook pdfでこれら全てが満たされたPDFが出てくるgitbookはやはり便利だった……。
そこで頑張って設定するならいっそpandocでいいのではという気が少しずつしてくる。
mdbook-latexを試してみた。8月にレポジトリが発生したレベルで新しいものなので苦労したが、まあ割となんとかなった。
gitbookのPDFほどの華やかさはないが、途中経過として普通にLaTeXを出力できるのでそこはどうとでもなる。
今後に期待というところだろうか。latex/pdf関連で何かできそうなことがあるか余暇で調べつつ、mdbookを使っていこうかな。
一応、Dockerを使ってGitBookのPDFを作ることができた。まだ少しは延命できそうではある。いいことかどうかは置いといて。
