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 で公開、を繰り返して良い感じのドキュメントを公開しよう！

MkDocs と GitBucket と GitBucket Pages Plugin で簡単ドキュメントサイト構築