Goal

先日Dockerのサイトを見ているとgithubにリンクが張ってありたどっていってmkdocsというMarkdown形式の文章を整形するツールが有ることを知りました。結構良さそうな感じなので使ってみました。

Howto

早速入れてみます。環境は MacOS 10.9 となります。

1
$ sudo pip install mkdocs

導入はこれで終わりです。 使い方も簡単で、文章(Markdown)を整形するフォルダを用意します。そのフォルダの中で処理を進めていきます。最終的には mkdocs buildコマンドで 静的なサイトを作ることが出来ます。

ディレクトリ構成として

1
2
3
4
5
mkdocs.yml
docs/
	index.md
	about.md
	abcd01.md

という構成です。mkdocs.ymlに構成を書いていきます。

構成ファイル mkdocs.yml

単純な形のサンプル。

1
2
3
4
5
site_name: MkLorum
pages:
- [index.md, Home]
- [about.md, About]
theme: readthedocs

もう少し設定する場合には、Configuration - MkDocs を参考にします。

プレビュー機能

プレビュー機能としてmkdocsでローカルにHTTPで起動する事が出来ます。実行後、http://local.host:8000 で接続してみるとかっこいい画面で表示されているのがわかります。

1
$ mkdocs serve

images

のような形で出力されます。

ビルド作業

問題なければ最後に静的ファイルを作成します

1
$ mkdocs build

これでローカルの ./site 以下にファイル群が作られます。

使いこなし

これらのソースをgitで管理するには echo ¥'site/¥' >> .gitignor で site/ を除いた形で作ると良いです。 出来上がったファイル群は静的なHTMLファイルなので github page とか amazon s3なんかにUpしておければ使い勝手の良いサイトができる事に成ります。

まとめ

すごく簡単に綺麗にマニュアルサイトとかが作ることが出来ます。すでにmarkdownの文章があれば見せ方としてWebサイトのように構築することが出来るので機会があれば積極的に使っていきたい。それにしても便利んだな。