読者です 読者をやめる 読者になる 読者になる

マークダウンをブラウザで見れるMkDocsをGitBucketと連携して自動更新する

git
こんにちは、久々に書きます、まだ新卒の久保田です。


今日は、最近とても便利で気に入っている仕組みを作ったので、そのことについてです。


さて、エンジニアってとても覚えること多いですよね。
一生勉強とはよく言ったものです。


みなさんはどのようにしてこの膨大な知識をためているでしょうか?
ノートですか?
それともQiitaなどのブログ?
それともパソコンの中にテキストファイルを書いているでしょうか?
こだわりの強い人はmarkdownかもしれませんね。
ものすごい頭いい人はそんなものはいらねぇっていうかもしれませんね。



僕は開発環境にdocsというディレクトリを作り、テキストファイルをためていっているのですが、
これがまた見づらいのです。僕もマークダウンで書きたい。でもブログとかは続かないからやりたくない。(そもそもメモ程度のことをブログにしたくない)


そんなとき、先輩に教えていただいたのが、「MkDocs」というサービス。
 
マークダウンで書いたファイルをブラウザで見れるようにしてくれるものです。
しかも検索機能のおまけつき。

これはいい!と思ったのですが、結局ローカルで運用するのはいつかやらなくなりそうだなと思い、
GitBucketと組み合わせて、こんな風にしようと思いました。
(GitBucketは、Githubのクローンで、個人でGithubがもてるみたいな感じです。)

slack_for_ios_upload_720



GitBucketのwebhookを利用し、pushされたら、MkDocsサーバーがpullして自動更新するという仕組みです。
これならローカルで書いたメモをgit で pushするだけでページが自動更新がされ、便利そう!
公開したくなかったらapacheにベーシック認証つければいいですし。


というわけで作っていきましょう。
1 - MkDocs用のサーバーとGitBucket用のサーバーを用意
僕はAWSのEC2でやりましたが、なんでもいいです。1つのサーバーでもいいですし、適宜読み替えてください。


まず、MkDocs用のサーバーをセットアップします。

sudo yum install python-setuptools
sudo easy_install pip
pip install mkdocs

#mkdocs用のプロジェクトを作成
mkdocs new mkdocs

#設定ファイルを編集(mkdocs/mkdocs.yml)
docs_dir: /path/to/mkdocs/docs #追記する


# 動作確認
cd mkdocs
mkdocs serve -a 0.0.0.0:8000
ip:8000 にアクセス 

mkdocs
 


こんなのがでてきたらOK!

ここで、デフォルトのdocsを消しておきます。(後にgitリポジトリをcloneしてそれを使うため)
 
rm -rf mkdocs/docs

gitをインストールします。
 
sudo yum -y install git


次に、GitBucket用のサーバーのセットアップです。

sudo yum install -y java-1.8.0-openjdk java-1.8.0-openjdk-devel java-1.8.0-openjdk-headless
sudo yum install -y tomcat --enablerepo=epel


# 動作確認
sudo service tomcat start 

ip:8080/gitbucket にアクセス


gitbucket



こんなのがでてきたらOK!
(初期パスワードはroot: rootです)



2 - ローカルにメモを書く用のgitリポジトリを作成

ローカルにメモをためて行く用のリポジトリを作っておきます。
mkdir docs
cd docs
git init
touch index.md
# index.mdを作らないとmkdocsのトップページがなくなります


3 - GitBucketにリポジトリを作成
この辺は普通のgitと同じです。

右上に New repositoryボタンがあります。


4 - first commit

作ったリポジトリにfirst commitしておきます

git add .
git commit -m 'first commit'
git remote add [url]
git push -u origin master


5 - ここからが面白いところです。作ったGitBucketのリポジトリweb hookを登録しておきます。
git にはフックという機能があり、こちらを使うと特定のアクションがあった後になんらかのイベントを起こせます。
(how to 上司にほめられるための git ~フックスクリプト編~ http://blog.engineer.adways.net/archives/git/howto/3.html#more)

GitBucketに先ほど作ったリポジトリの、右のほうにあるSettingをクリックし、左メニューのService Hooksをクリックします。
すると以下の画面が出てきます。

gitbucket_webhook




ここに、これから作るエンドポイントを登録しておきます。
(ここで指定するアドレスにアクセスすると、MkDocsがGitBucketのリポジトリをpullするスクリプトが動くようにこれからなります。)


6 - MkDocsに作ったリポジトリをclone
先ほどGitBucket用に作ったリポジトリをMkDocs用のサーバーにcloneしておきます。
自動更新を実現するため、一度git pullして、MkDocsの機能を使ってmarkdownからhtmlに変換する必要があるためです。


git clone [url]


そして、cloneしたリポジトリに移動して、パスワードを設定しておきます。これをしておくと、git pullするときに認証を自動で行います。

# cloneしたリポジトリで、./git/configを編集
originのurlのホストの前に以下の形式でユーザー名とパスワードを追記します

 
url = http://ユーザー名:パスワード@ホスト:8080/gitbucket...


7 - エンドポイントの作成

MkDocsのサーバーに、リクエストがきたらリポジトリからcloneし、
MkDocsのbuildの機能を使ってmarkdownから生成したhtmlを配置するruby プログラムを作ります。
一番の肝となるところですね。

僕はRubywebrickを使って作りました。


require 'webrick'

# デーモンで実行
Process.daemon

srv = WEBrick::HTTPServer.new({
  Port: 'GitBukcetのWebHookに登録したポート番号'
})

srv.mount_proc '/' do
  `git -C /path/to/mkdocs/docs pull`
  `sudo /usr/local/bin/mkdocs build -f /home/ec2-user/mkdocs/mkdocs.yml -d /var/www/html/`
end

srv.start

そしてこのプログラムを動かします。
 

8 - apacheインストール
さて、最後の工程です。
MkDocsには、markdownからhtmlに変換する機能があります。
その変換したhtmlを表示する必要があるので、apacheを使います。(webサーバーであればなんでもいいです。)


9 - ローカルからGitBucketに対してpush
お疲れ様でした!
ついに動作確認です。

ローカルからGitBucketに対してpushします。
うまく動けば、pushしたらMkDocsがそのイベントを受け取り、自分にpullしてhtmlファイルを作り、配備してくれるはずです!

cd path/to/docs
mkdir test
touch test/index.md
echo '# hoge' >> test/index.md
git add .
git commit -m 'test'
git push

MkDocsにアクセスし、タブにtestというリンクがあり、hogeが表示されたら終了です。


mkdocs_fin



これで自動更新、さらにスマホから閲覧可能!
いやー便利ですね!

これでどこでも復習し放題、環境が変わっても大丈夫!


*****
MkDocsは、プロジェクト直下にあるymlにテーマなどを決められます。
jsを書くなど、カスタマイズすればかなりリッチなサイトを構築できるので、 色々試してみてください!