BackEnd

markdownで書けるドキュメントツールのGitbookを試す

投稿日:2018年9月6日 更新日:

はじめに

こんにちは。開発ドキュメントとしてwikiを使うケースはままあると思いますが、皆さんはどんなツールをお使いでしょうか。GithubやBitbucketといったサービス付属のwiki、Qiita:TeamなどのSaaS、あるいはRedmineなどのツールに付属しているwikiだったり、もしくは自ら管理するサーバにPukiwikiなどを入れて運用することもあると思います。
その類のツールを調査していて行き当たったのが、今回ご紹介するGitbookです。

Gitbookとは

  • 名前にGitと付いていますが、Githubとは特に関係ありません。
  • 基本的には「マークダウン形式で書いたドキュメントをhtmlに変換するツール」です。
  • 変換されたhtmlをリモートのサーバに置いて閲覧することももちろん可能です。
  • node.jsさえインストールされていれば、とりあえず動きます。類似ツールに国産のCrowiがありますが、こちらはnode.js+Mongodbで動作します。
    .mdファイルさえあればどこにでも置けて閲覧できるので、Gitbookの方が手軽で運用しやすいかと感じています。
  • 特にプラグインなど入れずにデフォルトで記事の全文検索が可能な点が、Gitbookの長所のひとつだと思います。

では早速ローカルに導入してみましょう。環境はmacOS High Sierra 10.13.6です。

nvm

node.jsのバージョン管理は他の言語やツールと異なり乱立気味のようです。macであれば、ただ試すだけならhomebrewでもよいのですが、今回はnvmを使用します。

nvm公式のドキュメントに従ってインストールスクリプトを取得・実行します。

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash

実行すると、以下の2行が~/.bashrcもしくは~/.bash_profileに追記されます。

node.jsインストール

その時の最新LTSを入れておけば、基本的には問題ないと思います。
LTS = Long Term Supportの頭文字です。訳すと長期サポート版となるでしょうか。
node.jsと同時にnpm(node.jsのパッケージ管理ツール)も一緒に入ります。

Gitbook導入

インストール

gitbook-cliはGitbook作成をするためのコマンドラインツールです。

初期化

initで初期化、buildで.mdファイルからhtmlを生成します。

ローカルでブラウザから確認

生成されたhtmlをlocalhostで確認できます。自分だけのためのwikiであれば、これだけで事足ります。
実際にチームで運用することを考えると、Github/gitlab/Bitbucketなどにリポジトリを作成し、.mdファイルや静的ファイルをプッシュしていくことになるでしょうか。
リポジトリのコミットログ = 記事の編集履歴になるわけですね。

起動メッセージにあるアドレスhttp://localhost:4000にアクセスしてみましょう。

作成と編集

gitbook initしたディレクトリ~/gitbookに新しいファイルを作成します。ファイル名はtest.mdとします。
ターミナルでvi ~/gitbook/test.mdでもいいですし、エディタなどからGUIで新規作成してもOKです。
中身はひとまず下記の通りにしてみましょう。

見出し編集

ページの左側にあるのが見出しで、ここには~/gitbook/SUMMARY.mdの内容が出力されます。見出しを編集して新規記事へのリンクを作成しましょう。

ライブリロード機能がありますので、ページを更新せずに「テスト記事」という名前のリンクが見出しに表示されます。

さいごに

いかがでしたでしょうか。wikiツールは様々ありますが、サーバにインストールするタイプを選ぶのであれば、Gitbookはかなり良さそうだと感じています。
この手のツールはサーバ移転の際のデータ吸い出しが面倒だったりするのですが、基本的にはリポジトリ上の.mdファイルさえあればよく、身軽なところがいいですね。
チャートを簡単に描画できるmermaid.jsなるものもあるそうで、設計書・仕様書などもGitbookで事足りるのではないかと期待しています。

参考

page_footer_300rect




page_footer_300rect




-BackEnd
-

執筆者:


comment

メールアドレスが公開されることはありません。

CAPTCHA


関連記事

rails

Railsの低レベルキャッシュを使ってみた

1 はじめに1.1 環境2 ドキュメント3 準備3.1 configの確認3.2 キャッシュストア4 使ってみる4.1 #read、#write、#delete4.2 #fetch4.3 オプション4 ...

Go言語

Go言語 gocraft/workを使って常駐プロセスでジョブを処理させる

1 はじめに2 workの特徴3 workを使えるようにする3.1 Redisのインストール3.2 Go用のライブラリインストール4 Enqueue〜ジョブ実行まで4.1 Enqueue側4.2 ジョ ...

rails

関連するモデルのレコードを一緒に作成する方法

1 はじめに1.1 前提条件2 実装2.1 モデルの作成2.2 コントローラの作成2.3 Viewの作成3 さいごに はじめに フォームからレコードを作成する際に、関連するモデルのレコードを一緒に作成 ...

rails

Shrineでアップロードする際に画像を加工する

1 はじめに2 アップロードする画像のリサイズ2.1 Gemを追加2.2 Uploaderの修正3 サムネイルを作成する3.1 Uploaderの修正3.2 サムネイルを表示する4 バリデーションの追 ...

rails

Railsのバリデーション

1 はじめに2 基本的なバリデーション3 EachValidatorクラス4 Validatorクラス5 autoload_pathsの編集6 さいごに はじめに 今回はRailsのActiveRec ...

フォロー

follow us in feedly

AppLink

英語

page_side_300rect

2018年9月
« 8月 10月 »
 1
2345678
9101112131415
16171819202122
23242526272829
30 

アプリ情報

目標を達成したい方を応援する、TODOアプリもリリースしております。 下記のアイコンから無料でダウンロードできます。

Web版MyCoach

私たちはより広い方にコーチングを知ってもらいたいと考えています。 下記のサイトにて、コーチの方々を紹介しておりますので、よろしければご覧ください。