ITと筋トレの二刀流

未だゼロ刀流

GitBookでドキュメント作成〜導入編〜

f:id:tatsuyashi:20180801001953p:plain:w300

チームで開発を行う上で環境構築手順書やHow-toをドキュメントにして共有することは多いと思います。

今回はGitBookというライブラリを使用してMarkdown形式のドキュメントを作成し、チームメンバーに公開してみたいと思います。

まず、本日は第1部としてGitBookを導入してドキュメントを作成し、リポジトリへプッシュするというところまで実施します。

GitBookとは

www.gitbook.com

簡単に説明すると、

  • Markdown形式のドキュメント郡をツリー形式でHTMLに変換
  • Node.jsで実行
  • ローカルサーバー、ビルドの機能によりドキュメント開発をサポート

といった特徴があります。

私は今回初めてGitBookを利用しますが、採用した理由としては以下の2点になります。

  • 複数のMarkdownを束ねるのが得意そうだった
  • CLIでビルド可能なので、CIを使って自動でHTML化してS3にアップロード→HTMLをメンバーに公開という流れが作れそう

元々Markdownは好きでちょっとしたドキュメントやはてなブログMarkdownを使っていたということもあり、手順書やHow-toで本格的に導入してみようかなと思いました。

GitBook導入 (Windows)

では、ここから実際にGitBookを導入してみたいと思います。

Node.jsインストール

既にインストールされている場合はスキップしてください。

https://nodejs.org/ja/

推奨版もしくは最新版お好きな方を。

node、npmコマンドが使用できるようになっていればOKです。

コマンドプロンプトを開き、

C:\Users\user-name>node -v
v6.8.1
C:\Users\user-name>npm -v
v4.0.5

gitbook-cliインストール

gitbook-cliをインストールします。

npm install -g gitbook-cli

パッケージのツリーがコンソールに表示されれば完了です。

プロジェクト作成

任意のフォルダを作成し、以下のコマンドを実行します。

gitbook init

パッケージのツリーがコンソールに表示されれば完了です。

以下のようなファイルが作成されました。

├── README.md
└── SUMMARY.md
  • README.md → トップページ
  • SUMMARY.md → 一覧

のようなものだと思います。

新規ドキュメント追加

試しにサンプルのドキュメントを作ってみます。
docs配下に作成していくものとします。

ファイル構成

├── README.md
├── SUMMARY.md
└── docs
        └── sample.md


sample.md

# sample

## sample

### sample

sample


SUMMARY.mdも編集します。

# Summary

* [Introduction](README.md)
  * [sample](docs/sample.md)    ←ネストして書く

サーバー起動

gitbook-cliではローカルにWEBサーバーを建ててMarkdownを変換したHTMLが見れるようになります。

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

ブラウザでhttp://localhost:4000にアクセスすると、

f:id:tatsuyashi:20180801013928p:plain

f:id:tatsuyashi:20180801013949p:plain

HTMLで表示されています。

ビルド

gitbook build

ビルドすると_bookというフォルダが作成され、そこにHTMLや画像等のファイルが格納されます。
今の時点では特に使用しません。

AWS CodeCommit へのアップ

AWS CodeCommitでソース管理したいと思います。

リポジトリ作成

作成します。

f:id:tatsuyashi:20180801015333p:plain

GitBookプロジェクトをGit管理

GitBookプロジェクトはCLIでinitした時点ではGit管理されていないので、Git管理を行うようにします。

初期化

git init

リモートリポジトリの適用

今回はcloneしないので、手動でリモートリポジトリを適用します。

git remote add origin [リポジトリURL]

コミット

git add .
git commit -m "initial commit"

プッシュ

git push --set-upstream origin master

f:id:tatsuyashi:20180801022028p:plain

リポジトリへのプッシュがCodeCommit上で確認できました。

(補足) .gitignoreの設定

GitBookでbuildやserveすると_bookフォルダができますが、ソース管理としては不要なので.gitignoreに追記します。

.gitignore

_book/

まとめ

今回はGitBookの導入を行いました。CLIが整備されているサービスは導入が非常に楽で良いですね。
次回はCodeBuildを使用してHTML化してS3にアップロードして配信まで行いたいと思います。

(続く)