昨日任された業務を紹介しよう。
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が便利。