昨日任された業務を紹介しよう。
Web上でパワポの内容をWebページで見れるようにして！
というものだ。
こんなとき、MkDocsがとても便利。
MkDocsの公式に飛ぶ。
サイト自体がMkDocsで作られてる。 こんなページがMarkdownでお手軽に作れるのがMkDocs。 いちよPythonのアプリだけどPythonでコーディングするわけじゃない。
インストール
動作環境
MkDocs supports Python versions 2.6, 2.7, 3.3, 3.4, 3.5 and pypy.
を満たしていればOK
pipのインストール
pipはデフォルトでインストールされているはずだが、ない場合や古い場合、インストールが必要。
pipをすでにインストール済みの場合。
以下のコマンドでアップデートpip install --upgrade pipインストールしてない場合。
get-pip.pyをダウンロードして以下のコマンドpython get-pip.py
MkDocsのインストール
pipを使ってMkDocsをインストールする。
pip install mkdocs $ mkdocs --version mkdocs, version 0.15.3
※Windowsを使っている場合
python -m pip install mkdocs python -m mkdocs
Webページの構築
mkdocs new my-project cd my-project
Getting started is super easy.
super easyですね。
mkdocs.ymlというconfigファイルとdocsというドキュメントのソースファイルを入れるファイルが作られます。docsにはデフォルトでindex.mdが入ってます。MkDocsはビルドインのサーバーなので、ドキュメントを作りながらWeb上でどう表示されるのか見ることができる。
mkdocs.ymlと同じディレクトリ上で、以下のコマンドを打つと、サーバーが立ち上がる。
$ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory [I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000 [I 160402 15:50:43 handlers:58] Start watching changes [I 160402 15:50:43 handlers:60] Start detecting changes
適当なWebブラウザでhttp://127.0.0.1:8000/にアクセスすると、
こんな感じでデフォルトのホームページが見れる。
MkDocsはオートリロードに対応しているので、mkdocs.ymlやdocs内のファイルに変更を加えるとすぐにWeb上に反映される。
ドキュメントの追加
docs/ディレクトリに.mdファイルを追加することに加え、mkdocs.ymlを編集する必要がある。しなくても自動で読み込まれるが、アルファベット順で並べられるため、ドキュメントの順番を指定したい場合は編集する。
最上位の階層に2つのページを追加する場合、以下のように編集する。
pages: - 'index.md' - 'about.md'
このままではディレクトリの名前がページの名前として認識され、docs/index.mdと docs/about.mdページが追加される。
自分で指定した名前をページに与えたい場合は以下のようにする。
pages: - Home: 'index.md' - About: 'about.md'
階層を持った構造にしたい場合
以下のようにセクションタイトルの下に関連ページを並べれば、サブセクション構造を持ったページが作られる。
pages:
- Home: 'index.md'
- User Guide:
- 'Writing your docs': 'user-guide/writing-your-docs.md'
- 'Styling your docs': 'user-guide/styling-your-docs.md'
- About:
- 'License': 'about/license.md'
- 'Release Notes': 'about/release-notes.md'
ドキュメント中に画像やgithubのページを含めたい場合
docs/以下のディレクトリに適切に配置すればよい
例えばGithubのCNAREファイル、PNGフォーマットのscreenshot.png画像を追加したいとき、ファイルのレイアウトを以下のようにする。
mkdocs.yml
docs/
CNAME
index.md
about.md
license.md
img/
screenshot.png
あとはドキュメント中にマークダウン記法で書けばいいだけ。
Cupcake indexer is a snazzy new project for indexing small cakes.  *Above: Cupcake indexer in progress*
テーマの設定
ドキュメントをどう表示させるか(サイトの見た目)を変更する場合、 mkdocs.ymlファイルを編集し、themeを設定します。
site_name: MkLorum
pages:
- Home: index.md
- About: about.md
theme: readthedocs
theme: readthedocsに設定すると、こんな感じ。
ビルドインのテーマはmkdocsとreadthedocsしかないぽいけどサードパーティーにはいい感じのが結構ありそう
サードパーティーのテーマは以下から入手可能
MkDocs Themes · mkdocs/mkdocs Wiki · GitHub
テーマのカスタマイズに関しては以下を参考に
Styling Your Docs - MkDocs
Templateの利用
ある程度整ったTemplateが配布されてたりする。 Templateから作った方が、いろいろ勝手がわかりやすい。
HTMLへの出力
Markdownで作ったファイルをHTMLに出力できる。mkdocs.ymlと同じディレクトリで、
mkdocs build
これにより新しくsiteディレクトリが作られる。
$ ls site about fonts index.html license search.html css img js mkdocs sitemap.xml
sitemap.xml fileや mkdocs/search_index.jsonといったファイルも作られる。
gitでファイルを管理している場合、siteファイルはgitの管理下に置きたくないので、以下のコマンドで.gitignore fileに"site/"を追加する。
echo "site/" >> .gitignore
感想
絵文字が使えなかったのがとても残念だけどかなり便利。というかMarkdownが便利。