Git標準のMarkdownでドキュメントを生成できるGit派生サービスGitbookをローカルで使う

Gitbookというドキュメント生成ツール

Gitとはオープンソースパッケージ管理システムです。無料で利用出来るGitサーバーGithubが有名なので、名前を聞いたことがある人は多いかも知れません。Githubでは標準のドキュメントファイルにマークダウンを採用しています。だからと言うわけでは無いですが、Gitとマークダウンは相性がとても良いです。

Gitベースのドキュメント作成環境がGitbookです。Gitに由来する高機能なバージョン管理と、node.jsで作られたドキュメント生成用プログラムが合体したものです。Githubとのアカウント連携も出来て、非常に有用なツールです。

話は少しそれるのですが、Github社はオープンソースソフトウエアGitを使用したコードホスティングサーバー事業者に過ぎないので、Github社の作ったツールでは無いです。この辺りはオープンソースマニアなら間違えないようにしたいところです。

オフラインで使いたい

マークダウンで書いているGodotの和訳をGitbookを使って読めるドキュメントにしたいと思います。高度なバージョン管理をしたいわけではないのでGitサーバーは必要ありませんし、グループで使うわけでは無いので、オフラインで動くのが望ましいです。

まずはnode.jsを探していきます。


apt-cache search node-js
apt-cache search nodejs

ありました、Linux Mint 18 (Ubuntu 16.04 LTS)ではパッケージ名nodejsみたいです。


sudo apt-get install nodejs

nodejs -v
v4.2.6

インストールされていることが確認できました。

gitbook-cliをインストール

gitbook-cliをインストールします。これはnode.jsのパッケージ管理システムnpmで提供されているはずなので、npmをインストールします。


sudo apt-get install npm

コマンドラインインターフェースは良いものです。特にviやgeanyなどのシェルと合わせて使うことが前提のエディタとは素晴らしく良くマッチします。

それではgitbookをインストールしていきます。


sudo npm install gitbook-cli -g

-gはグローバルインストールオプションです。gitbookをシェルコマンドとして使えるようにするためのものです。


gitbook
/usr/bin/env: `node': そのようなファイルやディレクトリはありません

エラーが帰ってきました。


node
プログラム 'node' はまだインストールされていません。 次のように入力することでインストールできます:
sudo apt install nodejs-legacy

これはつまりnodejsというパッケージ名に既知の問題があって、nodeというパッケージ名が前提のシステムとの互換性確保のnodejs-legacyというパッケージを用意しましたと言うことなのでしょう。言われた通りにインストールします。


sudo apt install nodejs-legacy

再度実行してみます。


gitbook

Usage: gitbook [options] [command]

Commands:

ls List versions installed locally
current Display currently activated version
ls-remote List remote versions available for install
fetch [version] Download and install a <version>
alias [folder] [version] Set an alias named <version> pointing to <folder>
uninstall [version] Uninstall a version
update [tag] Update to the latest version of GitBook
help List commands for GitBook
* run a command with a specific gitbook version

Options:

-h, --help output usage information
-v, --gitbook [version] specify GitBook version to use
-d, --debug enable verbose error
-V, --version Display running versions of gitbook and gitbook-cli

パーフェクトですね。バージョンの表示はどうやら大文字のようです。npmのリポジトリにあるgitbookは3.2.0、gitbook-cliは2.3.0でした。

使ってみる

作業ディレクトリを作って初期化します。


mkdir ~/gitbook
cd ~/gitbook
sudo gitbook init

現在Godotのチュートリアルの和訳企画を進めていますが、今まで作ってきたファイルは~/ドキュメント/Tutorials/Learning-step-by-step/以下にあります。ディレクトリ配下全てを再帰的にコピーする-rオプションをを使ってコピーしてきます。


cp -r ~/ドキュメント/Tutorials/Learning-step-by-step/ ~/gitbook

SUMMARY.mdを以下のように編集します。


# Summary

* [ステップバイステップで理解する]
* [シーンとノード](Learning-step-by-step/Scenes-and-nodes.md)
* [インスタンス化](Learning-step-by-step/Instancing.md)
* [インスタンス化の続き](Learning-step-by-step/Instancing-continue.md)
* [スクリプティング](Learning-step-by-step/Scripting.md)
* [スクリプティングの続き](Learning-step-by-step/Scripting-continued.md)
* [シンプル2Dゲーム](Learning-step-by-step/Simple-2D-game.md)
* [GUIチュートリアル](Learning-step-by-step/GUI-tutorial.md)
* [見栄えするスクリーン](Learning-step-by-step/Splash-screen.md)
* [アニメーション](Learning-step-by-step/Animations.md)
* [リソース](Learning-step-by-step/Resources.md)
* [ファイルシステム](Learning-step-by-step/File-system.md)
* [シーンツリー](Learning-step-by-step/SceneTree.md)

ビルドコマンドしてサーバーをローカルに立ち上げます。


gitbook build
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 13 pages
info: found 1 asset files
info: >> generation finished with success in 8.4s !

gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 13 pages
info: found 1 asset files
info: >> generation finished with success in 9.3s !

Starting server ...
Serving book on http://localhost:4000

HTMLブラウザでhttp://localhost:4000を見ると、このようなよく見るドキュメントが生成されているのが分かります。

手直しするところがまだまだあるので、きちんと手を入れて近々公開します。それが終わったらGithubにも上げようと思います。

Add a Comment

メールアドレスの入力は任意です。(公開されることはありません)