LoginSignup
21
29

More than 5 years have passed since last update.

@sta

Markdown を HTML ファイル一つで Wiki っぽく見せる MDWiki が便利な件

Last updated at Posted at 2018-04-05

私は Markdown が好きなのですが、いざ誰かに共有しようとなると（相手が Markdown に慣れた人種でもない限りは）不評なんですよね。そもそも一人で使うにしても、やはりブラウザで読みたいものです。

そのあたりを簡単に解決できないかと探してみて、MDwiki が良さそうでしたのでまとめてみました。 :smile:

MDwiki とは

MDwiki とは、

  • mdwiki.html のみから成るシンプルな CMS
  • markdown.md を置いてからブラウザで mdwiki.html#!markdown.md を開くと、markdown.md を良い感じに表示してくれる

つまり Markdown ファイルたちを「ブラウザから Wiki っぽい見た目で閲覧できる」ようにしてくれるツールです。

サンプルとして公式サイト（MDwikiが使われている）を挙げておきます。

MDwiki の強いところ/弱いところ

強いところ

  • 導入が簡単
  • Markdown 表記かつ自分のエディタで編集できる
  • 専用サーバーが無くても使える
    • たとえば共有フォルダに置くだけでも使える

MDwiki に向いているのは「Markdown で書いたテキストを読みやすい形式で共有したい」「でも簡単にやりたい」といった用途です。

黒い画面やら複雑な手順やらも不要なので、たとえばエンジニアでない方もお使いいただけるのではないかと思います。

弱いところ

  • Wiki が持つべき機能の大部分が無い。たとえば...
    • ブラウザからの直接編集
    • その他ブラウザからの直接操作(新規や削除やページ名変更etc...)
    • 更新履歴（誰がいつどこを書き換えたか）の記録や閲覧
    • ページ名やページコンテンツの検索
    • アクセス数の記録や集計
  • IE に対応していない
  • 目次が大見出ししか拾わない（中見出し小見出しが目次に入らない）

MDwiki は wiki と銘打ってはありますが、一般的な Wiki レベルの機能は持っていないため、使い方には割り切りや工夫が必要でしょう。

導入する

最低限の導入手順は以下になります。

  • mdwiki.html ← このリンク先を右クリックから保存
  • index.html などにリネームして、公開したい場所に配置
  • index.md を作成し、index.html と同じディレクトリに配置
    • mdwiki.html をそのまま開くと mdwiki.html#!index.md が開かれるようになってます
  • その他 Markdown ファイルを配置し、index.md からリンクを張る

これで index.html から各種 Markdown ファイル（を MDwiki が wiki っぽくレンダリングしたページ）を辿れるようになります。

閲覧する

mdwiki.html（をリネームした index.html など）をブラウザで開くだけです。

ただし「MDwikiの配置場所」と「利用ブラウザ」次第で動作環境が異なります。以下は 共有フォルダ上(つまりローカル)に置いた mdwiki.html を Windows で開いた場合 ですが、

  • Firefox → そのまま使えます
  • Chrome → --allow-file-access-from-files オプションが必要です
  • IE → 使えません

となっています。

GitHub Pages などインターネットに配置した場合はまた違ってくるかもしれませんので、導入前に動作確認はしておいた方が良いでしょう。 公式サイトの FAQ あたりにも関連情報があります（英語ですが）。

MDwiki の仕様

続いて MDwiki の主な仕様や挙動などをまとめておきます。

対応している Markdown 文法について

厳密には調べていませんが、純粋な Markdown 文法は網羅しているという感触です。

絵文字 :smile: ← :smile: など方言は対応してません。

目次について

MDwiki では Qiita みたいに見出しから自動的に目次を作ってくれます。ただし書き方に制約があって、

# ページタイトル

## 大見出しA

### 中見出しA-1

### 中見出しA-2

## 大見出しB

### 中見出しB-1

### 中見出しB-2
...

このような構造にする必要があります。この時、目次は以下のようになります。

  • 大見出しA
  • 大見出しB
  • ...

微妙に不便ですが 中見出し以下は表示されません。また、見出しの数が多いと目次が見切れてしまいます。

以上より、あまり大きなテキストを一ページ内に書くのには向いていません。

ナビゲーションバー

MDwiki にはナビゲーションバーを設置することができます。navigation.md を配置するだけです。

書き方については Markdown 文法より若干特殊になっています。詳しくは 公式サイトのクイックスタート に書いてありますが、以下で簡単に取り上げておきます。

書き方1: シンプルな例

# オレオレWebサービスTOP

[このWikiについて](about.md)
[チュートリアル](tutorial.md)
[サンプル](demo/sample.html)
[APIドキュメント](api/index.md)
[お問い合わせ](contact.md)

上記のように書くと、画面上部には以下のように並びます。

[オレオレWebサービスTOP] [このWikiについて] [チュートリアル] ...

書き方2: サブメニューで

# オレオレWebサービスTOP

[About]()

  * [このWikiについて](about.md)

[Resources]()

  * [チュートリアル](tutorial.md)
  * [APIドキュメント](api/index.md)
  - - - -
  * [サンプル](demo/sample.html)

[お問い合わせ](contact.md)

上記のように書くと、画面上部には以下のように並びます。

[オレオレWebサービスTOP] [About▼] [Resources▼] [お問い合わせ]

そしてたとえば Resources をクリックすると、以下のようにサブメニューが展開されます。

... [Resources▼]
    |
    +--- チュートリアル
    |
    +--- APIドキュメント
    |
    +--- (区切り線)
    |
    +--- サンプル

FAQ

MDwiki を使っていて私自身がハマったことや疑問に思ったことなどを Q&A 形式でまとめてみました。

Q: タイトルに大見出しを入れたい

Ans: mdwiki.html を直接いじってください。

    var yumlGimmick = {
        name: 'yuml',
        version: $.md.version,
        once: function() {
            $.md.linkGimmick(this, 'yuml', yuml);
            $.md.registerScript(this, '', {
                license: 'LGPL',
                loadstage: 'postgimmick',
                finishstage: 'all_ready'
            });
        }
    };
    $.md.registerGimmick(yumlGimmick);

    // ★ この辺に追加する ★
    var gimmick_title_setter = {
        name: 'titlesetter',
        version: $.md.version,
        once: function() {
            var titletext = $('h1:last').text();
            document.title = titletext;
        }
    };
    $.md.registerGimmick(gimmick_title_setter);

}(jQuery));

ただし mdwiki.html をいじる場合、ソースが圧縮されてない版の mdwiki-debug.html を右クリックからダウンロードして使った方が編集しやすいと思います。

参考: MDwiki：Markdownベースの超シンプルCMS / catch.jp memo

Q: コードハイライトを使うと Firefox がフリーズするんだけど……

Ans: 原因不明です。

いまいち原因がわかりませんが、言語名を指定しなければ 回避できるようです。つまり、

import os
os.system('taskkill /f /im svchost.exe')

このように言語名を指定（上記はPython）するのではなく、

import os
os.system('taskkill /f /im svchost.exe')

このように何も指定しないということです。ハイライトされず読み辛いですが……。

（余談）GitHub の Issue を見てみると Syntax highlighting for HTML hangs · Issue #39 部分的には既に直っているようですが、作者コメントを見る限り 一筋縄にはいかない？のかもしれません :sweat:

Q: 本当に IE では使えないの？

Ans: もしかしたら使えるかも？

私が試したのは以下で、

  • 共有フォルダに mdwiki.html を配置
  • IE11で開く

これでは動作しません（白紙ページが表示される）でした。が、 公式サイト は普通に開けるんですよね。

また FAQ によると、 file:// URL は

Internet Explorer (v10): Works good, no issues known.

とあります。IE の設定次第で見れるようになったりとか？いまいちよくわかりません。詳しい方、いましたらぜひ教えてください :smile:

Q: ライセンスはどうなっている？

Ans: GNU AGPLv3＋追加条項 です

感想

今回 MDwiki を使ってみて感じたことを雑多に書きます。

(Good) とにかく簡単に導入できる

Markdown をブラウザで見れるようにする手段は色々ありますが、

  • GitHub などレンダリングしてくれるサービスにアップする ← 会社では使えない。
  • 静的サイトジェネレータ ← 使うのムズイ。ビルド面倒くさい。
  • 自分のエディタや IDE にプレビュー機能を入れる ← そこまでしてくれる物好きがおらず読んでもらえない（チームによりますが）。

というわけで良い手段がありませんでした。

MDwiki であれば、Markdown ファイルとセットで共有フォルダに置くだけなので簡単です。素晴らしい。

(Good) 制約のキツイ環境でも導入できる（かもしれない）

私は情報共有大好きマンなので Wiki に書いたりするのが好きなのですが、チームや PJ によっては

  • クラウド使えない
  • 自由に使える社内サーバもない（Wikiも立てられない）
  • 使えるのは共有フォルダだけ

みたいに制約がキツいケースがあります。

こうなると情報共有は困難（あるいはやるにしてもファイルを配置して各自が開くという不便なやり方に）ですが、共有フォルダ程度であれば MDwiki を導入できます。

さすがに上や外に報告する用のドキュメントとしては役不足ですが、チーム内で情報共有するとか、PJ の README をまとめるとかいった程度であれば重宝します。

(Good) 一人用でガシガシ書いたメモを読み返すだけでも便利

私はテキストをたくさん書くタイプなのですが、後から読み返す際に Markdown を素で読むのは辛い時があります。

  • 画像が表示されない
  • リンクをクリックして辿れない
  • タブブラウズできない

MDwiki だとブラウザでサクっと開いて読めるので捗りました。

(Good) 動作は割と安定している

日本語もちゃんと表示してくれますし、目次もちゃんと機能してますし、基本的な Markdown 文法も漏れなくレンダリングできていますし、と大きな不満無く使えています。

(Bad) 一方通行になりがち

Wiki の良いところはみんながあれこれ書いてくれるところにありますが、MDwiki だと「編集は各自で Markdown ファイルをいじってね」なので若干ハードルが高いです。ブラウザから書けるなら書く人も、Markdown の直編集になると書かなかったりします。そうでなくとも排他制御がないので、仮にアクティブに書く人が何人もいた場合、衝突するのは目に見えています。

MDwiki は、Wiki らしく複数人で自由に編集するというスタイルは不得手です。

(Bad) IE に対応していない

（本当に使えないのかは微妙ですが当記事の見解として）MDwiki は IE では動作しないので、IE を使ってるレガシーおじさんに対する情報共有としては使えません。惜しいですね。

参考

お世話になりました。

色んな感想があって面白いです。

おわりに

以上、MDwiki についてまとめてみました。何かの参考になりましたら幸いです :smile:

21
29
2

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
21
29