TL;DR
MkDocs は GitBucket の Pages プラグインとも相性良くて簡単！
はじめに
ちょっと GitBucket の利用者向けガイドみたいなものを公開したくて、Markdown あたりで書いたものを簡単に公開できる仕組みを探していた。
普段静的サイトジェネレータとしては Nikola を使っているけど、ちょっと設定が多いしデフォルトだとブログっぽい感じになりすぎるので別のを探した。
MkDocs というのを見つけて試してみたところ、簡単で GitBucket とも相性良かったので採用した、という話。
準備
- GitBucket に Pages Plugin を入れておく
- Python が動く環境を用意しておく
- Git が（略
インストール
pip install mkdocs
システム全体に入れるか、--user したり virtualenv で入れたり pyenv で入れたりはお好みで。
サイトの作成
mkdocs new MkDocsSample
で MkDocsSample という名前のディレクトリに雛形が出来る。
GitBucket に置く
GitBucket でリポジトリを作成しておいて、MkDocsSample の中で git init git remote add origin http://server/git/user/repo.git しておく。あと、.gitignore に site/ と書いておいた方が良い。
で、適当に git add . git commit -m "initial commit" して、git push -u origin master で生成元の Markdown を入れておく。
サイト生成＆Pages に公開
mkdocs コマンドはオプションも少なく非常にシンプル。
Usage: mkdocs [OPTIONS] COMMAND [ARGS]...
MkDocs - Project documentation with Markdown.
Options:
-V, --version Show the version and exit.
-q, --quiet Silence warnings
-v, --verbose Enable verbose output
-h, --help Show this message and exit.
Commands:
build Build the MkDocs documentation
gh-deploy Deploy your documentation to GitHub Pages
json Build the MkDocs documentation to JSON files...
new Create a new MkDocs project
serve Run the builtin development server
-
buildで site/ 以下に HTML を生成する。 -
serveで localhost:8000 に HTTP サーバを起動するのでブラウザでチェック（Live reload対応） -
gh-deployで GitHub Pages や GitBucket Pages が使うgh-pagesブランチにsite/の中身を入れて自動的に push してくれる。 -
jsonで JSON ファイルを生成する・・・って何に使うんだろ？
ということで、mkdocs gh-deploy と打つだけで GitBucket の gh-pages ブランチに Push されているので、http://server/user/repo/pages/ という URL でドキュメントが公開された状態になっている。簡単。
コンテンツの作成
あとは docs/ 以下に *.md を放り込んだり、mkdocs.yml を色々いじったりして、mkdocs serve で確認、確認が終わったら mkdocs gh-deploy で公開、を繰り返して良い感じのドキュメントを公開しよう！