notebook

都内でWEB系エンジニアやってます。

MkDocsでドキュメント管理

メモとか、ブログの原文とかをmarkdownで保存していたのですが、管理方法をどうしようかと思っていたところでたまたまMkDocsの話を耳にしたので試してみました

カスタマイズも設定も簡単にできるし見た目も十分なのでローカルでのmarkdownドキュメント管理をMkDocsで行うことにしました

MkDdocs

ドキュメント読めばほとんどわかるし重複も発生しますが今回やったことを残しておきます

インストール

たったこれだけ

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

検索

ドキュメント内を検索することができます、すごい

ただこれがあるのは一部のテーマのみのようです

f:id:swfz:20150728031445p:plain

こんな感じで見出しに飛べるようです

f:id:swfz:20150728031504p:plain

カスタマイズ

色々カスタマイズできるようなので色々試してみます

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 themes

今回はmkdocsの方のディレクトリから拝借しました

ファイルは下記

  • 404.html
    • エラー
  • base.html
    • ベース
  • nav.html
    • ナビゲーション
  • nav-sub.html
    • サブナビゲーション
  • toc.html
    • 記事の左側のナビゲーション
  • content.html
    • 記事本体

f:id:swfz:20150728031522p:plain

中身は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

まずはコードシンタックスを変えてみます

参考

記事中のリンクから使いたいテーマを選んで読みこませればいけるようですね

気分で変えられるように設定ファイルを変更すれば適用できるようにしました

  • 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

f:id:swfz:20150728031539p:plain

toc.html

見出しの追加

目次の見出しはh1,h2のみ表示されるようになっているので表示範囲を増やしてh3まで表示させるようにしました

<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
  • 公開前も含めたすべてのファイルの情報を記述したjsonファイルを用意

  • data.json

[
  { "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.js

c3についてはまた今度、でもとても簡単に使えます

f:id:swfz:20150728031554p:plain

管理

site以下にファイルが生成されるので gitで管理するには .gitignoreに下記記述を行い管理するのがいいようです

  • .gitignore
site/

静的ファイルのみで閲覧ができるのでS3にあげたりすれば下手にブログ立ててサーバ代かけるよりよっぽどいいですね

その他

実際に使ってはないけど便利そうな機能

感想

今回は公開とかはしない予定だったのでデプロイ関連まではやらなかったですがそんなに難しくはなさそうなイメージ

目標立てて進捗グラフとかも作ればモチベーション維持にも一役買ってくれそう。。。?

簡単なサイトならS3だけで済ませられるのでサーバ要らないですね

低予算万歳!

他にも機会があれば使っていきたいなと思いました