Markdown を HTML で読む手段として MkDocs と MDwiki を試したので優劣を書く

Markdown は書きやすく、そこそこ読みやすい記法だが、それでも plain text なので不便である。定石は HTML に変換して読むことだと思う。で、その変換手段として色々あるんだけど、今回は MkDocs と MDwiki を比較してみる。

前提

記事のまとめ方

  • V.S. の形で「どちらが優れているか or ドローか」を主観でまとめている
  • 細かい使い方や拡張方法などは取り上げない

MkDocs とは?

いわゆる静的サイトジェネレータ(ビルドすることで原稿ファイルから HTML ファイルを生成するタイプ)。分かる人向けに言えば「Markdown で書ける Sphinx 」。

MDwiki とは?

mdwiki.html#!index.md にアクセスすると index.md を HTML に変換して表示してくれるツール。

使い分けについて

「一人用 or チームメンバー間で見るだけ」みたいな小さい単位で、てっとり早く HTML で読みたいなら MDwiki。

ただ MDwiki は読み心地が微妙なのと、カスタマイズの能力にも限界があるのとで、そのうち物足りなくなってくる。そうなったら MkDocs が良いだろう。導入やカスタマイズは難しいが、MDwiki を凌ぐ読み心地とカスタマイズ能力を持っている。

(1) 導入面

Winner: MDwiki

導入ハードル

Winner: MDwiki

MDwiki はダウンロードした MDwiki.html を配置するだけで完了する。MkDocs は Python と pip のインストールが必要。

HTML 変換の手間

Winner: MDwiki

MDwiki はページ読込時に動的に変換するので変換コストはゼロ。MkDocs は事前にビルドが必要。

ライセンス

Winner: MkDocs

MDwiki には additional terms(追加条項)として「(MDwikiのクレジットが表示された)フッターを消すなよ」等があり、商用ユースでは若干不格好かなという印象。

(2) 見た目

Winner: MkDocs

URL のキレイさ

Winner: MkDocs

  • MkDocs: https://example.com/hoge.html
  • MDwiki: https://example.com/index.html#!hoge.md

CSS カスタマイズ

Draw.

どちらも CSS をいじって見た目をカスタマイズできる。

テーマの変更

Winner: MkDocs

MkDocs はサポートしている。MDwiki はサポートしていない。

(3) 生成サイトの使い心地

Winner: MkDocs

TOC(目次)

Winner: MkDocs

MkDocs は TOC の生成が安定しているし、テーマ次第だが見出し階層をインデントで階層表示してくれたりもして見やすい。

というより MDwiki の TOC は出来が悪い。中見出し(## ...)しか表示してくれない、目次が長いと見切れたり消えたりするバグがあるなど。

ナビゲーションバー

Draw.

どちらもサポートしている。ネストも可能。

細かいことを書くと、

  • MDwiki: navigation.md に書き並べる&表示は画面上部にバーのみ
  • MkDocs: mkdocs.yml に書き並べる&表示はテーマ次第(上部にバーだったりサイドバーだったり)

全文検索

Winner: MkDocs

MkDocs は検索できる。それでもデフォルトでは日本語検索できなかったりするが、 material テーマでは設定を追加すればできるようになる みたい。

MDWiki は検索機能がそもそも無い。

見出しのアンカーリンク

Draw.

MkDocs はテーマによって生成したりしなかったり。

MDwiki は生成するが、アンカーマークが見出し行の次行に表示される(そして表示時に行が動的に一つ増えるため表示全体がずれる)のが微妙。

ローカルサイトへのアクセス

Winner: MkDocs

MkDocs だはローカルに置いた index.html も普通に読める。

(2018/08/02 追記) ローカルで読むためには mkdocs.ymluse_directory_urls: false の指定が必要です。詳しくは MkDocs で生成したサイトをローカルで開くと index.html が開かれない問題 - stamemo を参照

MDwiki だと IE と Chrome では読めない(Chrome ではコマンドライン引数を付け加えればできる)。これは MDwiki は動的に md ファイルをロードするせいでブラウザ側のセキュリティに引っかかってしまうため。

(4) Markdown 記法

Winner: MDwiki

サブリストのネスト表記

Winner: MDwiki

MDwiki は 2 スペースでも動く。MkDocs では 4 スペースでないと動かない。

URL の自動ハイパーリンク化

Winner: MDwiki

MDwiki はしてくれる。MkDocs はしてくれない。

(5) その他未分類

SEO 効果

Winner: MkDocs

MkDocs は静的サイトなので SEO 対策できる。というより MDwiki がコンテンツを全部動的に生成するために SEO 対策しづらい。

サポート状況

winner: MkDocs

MkDocs は 2018/06/28 現在も活動している。MDwiki は(いつからか知らないけどたぶんここ数ヶ月の間に) Read Only になっている