GitBookでドキュメント作成〜導入編〜
チームで開発を行う上で環境構築手順書やHow-toをドキュメントにして共有することは多いと思います。
今回はGitBookというライブラリを使用してMarkdown形式のドキュメントを作成し、チームメンバーに公開してみたいと思います。
まず、本日は第1部としてGitBookを導入してドキュメントを作成し、リポジトリへプッシュするというところまで実施します。
GitBookとは
簡単に説明すると、
- Markdown形式のドキュメント郡をツリー形式でHTMLに変換
- Node.jsで実行
- ローカルサーバー、ビルドの機能によりドキュメント開発をサポート
といった特徴があります。
私は今回初めてGitBookを利用しますが、採用した理由としては以下の2点になります。
元々Markdownは好きでちょっとしたドキュメントやはてなブログでMarkdownを使っていたということもあり、手順書やHow-toで本格的に導入してみようかなと思いました。
GitBook導入 (Windows)
では、ここから実際にGitBookを導入してみたいと思います。
Node.jsインストール
既にインストールされている場合はスキップしてください。
推奨版もしくは最新版お好きな方を。
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にアクセスすると、
↓
HTMLで表示されています。
ビルド
gitbook build
ビルドすると_bookというフォルダが作成され、そこにHTMLや画像等のファイルが格納されます。
今の時点では特に使用しません。
AWS CodeCommit へのアップ
AWS CodeCommitでソース管理したいと思います。
リポジトリ作成
作成します。
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
リポジトリへのプッシュがCodeCommit上で確認できました。
(補足) .gitignoreの設定
GitBookでbuildやserveすると_bookフォルダができますが、ソース管理としては不要なので.gitignoreに追記します。
.gitignore
_book/
まとめ
今回はGitBookの導入を行いました。CLIが整備されているサービスは導入が非常に楽で良いですね。
次回はCodeBuildを使用してHTML化してS3にアップロードして配信まで行いたいと思います。
(続く)