メモとか、ブログの原文とかをmarkdownで保存していたのですが、管理方法をどうしようかと思っていたところでたまたまMkDocsの話を耳にしたので試してみました
カスタマイズも設定も簡単にできるし見た目も十分なのでローカルでのmarkdownドキュメント管理をMkDocsで行うことにしました
ドキュメント読めばほとんどわかるし重複も発生しますが今回やったことを残しておきます
インストール
たったこれだけ
pythonは2.7.8?以上が必要らしいです
sudo yum install python-setuptools easy_install pip pip install mkdocs
プロジェクト作成
mkdocs new sample-project cd sample-project tree . |-- docs | `-- index.md `-- mkdocs.yml
mkdocs.ymlに各種設定を記述していきます
markdownファイルはdocs以下に置いていきます
プレビュー
ローカルにサーバを起動できる
docs以下のファイルの変更を感知して自動でビルドしてくれます
client側でも自動で再読み込みしてくれる実装になっているので編集だけに集中できます
これだけでも入れる価値ありそうな気がします
mkdocs serve
VMにサーバを立ててる場合などはそのサーバのIPをオプションで渡してあげればアクセスできます
mkdocs serve --dev-addr=192.168.20.11:8000
ビルド
編集してきたmarkdownなどを静的ファイルに変換します
mkdocs build
静的ファイルたちがsiteディレクトリ以下に生成されます
これをnginxとかで配信すればサイトの出来上がり! ちょっと感動
テーマ
built-in themesがいくつかあるのでそれを設定してしまうのが一番早いです
デフォルトはmkdocs
- mkdocs.yml
theme: flatly
検索
ドキュメント内を検索することができます、すごい
ただこれがあるのは一部のテーマのみのようです
こんな感じで見出しに飛べるようです
カスタマイズ
色々カスタマイズできるようなので色々試してみます
CSS,javascriptの設定変更
カスタマイズの粒度もjsのみ、cssのみと色々設定できる模様
ファイルはdocs以下を探しに行く
extra_javascript: [sample.js] extra_css: [style.css]
カスタムテーマ
デフォルトで読んでくれていたテンプレートを読みに行かずに設定したディレクトリから静的ファイルを生成します
- ディレクトリ構成
docs/ index.md about.md custom_theme/ base.html ...
- mkdocs.yml
theme_dir: 'custom_theme'
1から書くこともできますがさすがにあれなのでデフォルトのテーマをコピーしてそれを編集していきます
今回はmkdocsの方のディレクトリから拝借しました
ファイルは下記
- 404.html
- エラー
- base.html
- ベース
- nav.html
- ナビゲーション
- nav-sub.html
- サブナビゲーション
- toc.html
- 記事の左側のナビゲーション
- content.html
- 記事本体
中身はjinja2のテンプレートエンジンで書かれているので文法覚えれば自由にカスタマイズできそうです
extra
設定ファイルに extraとして設定することで自由な変数をセットできます
- mkdocs.yml
extra: version: 1.0.0 links: - https://github.com/mkdocs - https://docs.readthedocs.org/en/latest/builds.html#mkdocs - http://www.mkdocs.org/
- 各テンプレートファイル
{{ config.extra.version }} {% if config.extra.links %} <ul> {% for link in config.extra.links %} <li>{{ link }}</li> {% endfor %} </ul> {% endif %}
base.html
code syntax
まずはコードシンタックスを変えてみます
- highlight.jsを使ってみます
参考
記事中のリンクから使いたいテーマを選んで読みこませればいけるようですね
気分で変えられるように設定ファイルを変更すれば適用できるようにしました
- mkdocs.yml
extra: highlightjs: version: 8.6 syntax: atelier-sulphurpool.dark
テンプレート側ではこんな感じ
- base.html
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/{{ config.extra.highlightjs.version }}/styles/{{ config.extra.highlightjs.syntax }}.min.css"/> <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/{{ config.extra.highlightjs.version }}/highlight.min.js"></script> <script> $(document).ready(function() { $('pre').each(function(i, block) { hljs.highlightBlock(block); }); }); </script>
content.html
meta情報を設定する
markdownのmeta情報として最初にいくつか記述してあげることでそれに応じた処理をさせることができる模様
デフォルトでは下記のようにしてあげることで右上にラベルが出てくる
公式ドキュメントではこれにgithubへのリンクを張って直接飛べるようにすることもできるよっていう風な事が書いてありました
- samaple.md
source: sample.md image.png
toc.html
見出しの追加
目次の見出しはh1,h2のみ表示されるようになっているので表示範囲を増やしてh3まで表示させるようにしました
- toc.html
<div class="bs-sidebar hidden-print affix well" role="complementary"> <ul class="nav bs-sidenav"> {% for toc_item in toc %} <li class="main {% if toc_item.active %}active{% endif %}"><a href="{{ toc_item.url }}">{{ toc_item.title }}</a> <ul class="nav bs-sidenav"> {% for toc_item in toc_item.children %} <li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a> {% if toc_item.children %} <ul > {% for toc_item in toc_item.children %} <li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li> {% endfor %} </ul> {% endif %} </li> {% endfor %} </ul> </li> {% endfor %} </ul> </div>
特別ページの設置
content.htmlで、{{ content }} を表示する前にファイルのmeta情報を参照していたので、集計用のページを設ける事ができそうだと思いやってみました
ちょっとコンセプトとはずれてしまうので微妙かも知れませんが、こういうこともできるってところですね
- repotページ用のmarkdownを用意、設定
このページはすべてテンプレート側で処理してしまうのでmeta情報だけ記述したmarkdownを用意します
pagetype: report
[ { "title": "page1 title", "url": "category/sample1", "date": "2015-01-02", "type": "blog" }, { "title": "page2 title", "url": "category/sample2", "date": "2015-02-20", "type": "qiita" }, { "title": "page3 title", "url": "category/sample3", "date": "2015-03-23", "type": "blog" } ]
- content.htmlでコンテンツの呼び出し条件を分ける
{% if meta.pagetype|join("") == 'report' %} {% include "report.html" %} {% else %} {{ content }} {% endif %}
- 新たなテンプレートでデータを用いた集計ページ(report.html)を作成
var req = new XMLHttpRequest(); req.open("GET", "/data.json", false); req.send(null); var datalist = JSON.parse( req.responseText );
あとは用途に合わせて表示させるだけです
今回はc3.jsというのを使ってみました、d3.jsのラッパーみたいな位置づけのようです
c3についてはまた今度、でもとても簡単に使えます
管理
site以下にファイルが生成されるので gitで管理するには .gitignoreに下記記述を行い管理するのがいいようです
- .gitignore
site/
静的ファイルのみで閲覧ができるのでS3にあげたりすれば下手にブログ立ててサーバ代かけるよりよっぽどいいですね
その他
実際に使ってはないけど便利そうな機能
- 設定ファイルでgoogle analyticsを設置できる
- github pageとの連携
感想
今回は公開とかはしない予定だったのでデプロイ関連まではやらなかったですがそんなに難しくはなさそうなイメージ
目標立てて進捗グラフとかも作ればモチベーション維持にも一役買ってくれそう。。。?
簡単なサイトならS3だけで済ませられるのでサーバ要らないですね
低予算万歳!
他にも機会があれば使っていきたいなと思いました