2017-9-04

MDwiki：Markdownベースの超シンプルCMS

Category: Tech

MDwikiは、Markdownベースのとてもシンプルなコンテンツ管理ツール。

Wikiというよりも、Flat-File CMSというジャンルなのかもしれない。

非常に便利だったけど、ほとんど日本語情報がなかったので整理しておきます。

MDwiki - Markdown based wiki done 100% on the client via javascript

特徴

mdwiki.htmlというひとつのファイルだけあれば利用できる

で、Markdown記法で書かれたテキストファイル(拡張子 .md、以下mdファイル)を、このmdwiki.htmlと同じフォルダに置く。

これだけで、mdファイルがWebページとして表示されます。

サーバーにスクリプトやDBを設置する必要もないし、いちいちmdファイルを変換する必要もありません。

mdwiki.htmlのなかに、JavascriptとBootstrapベースのテンプレートが埋め込まれている
Gimmicks（ギミックス）という追加機能で、GoogleマップやFacebookなど今どきのソーシャルサービスにも対応。
クライアントサイドでhtmlが作られるので、以前は検索エンジンに引っかからなかったが、最近は対応しているらしい。
作ったのは、 Timo Dörr(Dynalon)さん。ライセンスは、GPLv3 + 追加条項

サンプル

はじめ方

ドキュメントをmdファイルとして準備。
文字コードはUTF-8
1行目は、見出し1にする(#記号)
最初のページのファイル名は、index.mdとします。
MDwikiをダウンロード。>> https://github.com/Dynalon/mdwiki/releases
index.mdとmdwiki.htmlを同じフォルダにおく
mdwiki.htmlを開くと、自動的にindex.mdが変換されて表示
どこかにWebサーバーがあるなら、そこにおいてもいい。社内とかイントラネットで使うなら、XAMPPとか用意するのが早いかも。

使い方

使い方も、とてもシンプル

ページアクセス

「mdwiki.html」を開く場合は、index.mdが変換されて表示される
下記のように「mdwiki.html」の後ろに「#!」＋mdファイル名をつけると、そのmdファイルが変換されて表示される
例 http://example.com/mdwiki.html#!myfile.md

ページ内のナビゲーション

見出し1が、ページタイトルになって、見出し2が複数あるとサイドに一覧表示される

書式設定

markdownでやる。画像やリンクもOK。

http://dynalon.github.io/mdwiki/#!layout.md

ナビゲーションバー

下記のように、navigation.mdファイルを書いて、同じフォルダに置くと、上部の共通ヘッダーにナビゲーションバーが表示される

# サイトタイトル

[Home](home.md)
[About](about.md)
[Download](download.md)

ページパス

URL	表示されるページ
mdwiki.html	index.md
mdwiki.html#!myfile.md	myfile.md
mdwiki.html#!myfolder/	myfolder/index.md
mdwiki.html#!myfolder/myfile.md	myfolder/myfile.md

各種設定

テーマの切り替え

公式サイトの右上にあるやつ。

Theme chooserというギミックスでできる。

http://dynalon.github.io/mdwiki/#!customizing.md#Theme_chooser

navigation.mdに、こんなふうに記述すると、テーマ選択メニューが表示される。

[gimmick:themechooser](Choose theme)

navigation.mdに、こんなふうに記述すると、デフォルトテーマを指定できる。

[gimmick:theme](flatly)

ギミックス

Gimmicks（ギミックス）という追加機能で、GoogleマップやFacebookなど今どきのソーシャルサービスにも対応。

こんなのが、ありますね。

Alerts
GitHub Gists
Facebook Likebutton
Fork me on GitHub - Ribbon
Google Maps
UML Diagrams via yUML.me
Math
Twitter
Youtube
Disqus

http://dynalon.github.io/mdwiki/#!gimmicks.md

スタイルシート

mdwiki.htmlに埋め込まれているので、そこをいじる。

デフォルトでは、Twitter bootstrapが組み込まれていて、さらに追加のcssがある。

個人的には、追加部分をmdwiki.cssという外部cssファイルに切り出して、そちらでいじっている。見出しなどのスタイルを変えるときも、そこでやる。

そのために、mdwiki.htmlの194行目あたりに以下のコードを埋め込む。

link rel="stylesheet" href="style.css"

もしも、自分でMDwikiをビルドできるなら、style/custom.cssにスタイルを追記できる。

ページ一覧の取得

ページ一覧を取得する方法がないので、navigation.mdで上部メニューに手動で追加する。

まあ、wikiなので、ページ一覧を表示させるのは、本質的ではないということかも。

設定ファイルによるカスタマイズ

config.jsonというファイルを同じフォルダにおくと、カスタマイズできる。こんな設定がある。

サイドナビのON/OFF
オリジナルの改行指定
フッターテキストの追加
見出しのアンカー記号
タイトル(ただし、Google検索の結果には反映されない。そこを変えるには、htmlのtitleタグを修正する)

{
    "useSideMenu": true,
    "lineBreaks": "gfm",
    "additionalFooterText": "All content and images &copy; by John Doe",
    "anchorCharacter": "#",
    "title": "ACME Industries Wiki"
}

詳細は、http://dynalon.github.io/mdwiki/#!customizing.md#Configuration

追加のJavascript

こんな感じで、mdwiki.htmlの200行目(mdwiki.jsの一番最後)に追加すると、「MyGimmick」というギミックスが追加できる。該当ページが表示された後に、1回だけコードを実行してくれる。

(function($) {
    'use strict';
    var myGimmick = {
        name: 'MyGimmick',
        version: $.md.version,
        once: function() {
            // write code here

        }
    };
    $.md.registerGimmick(myGimmick);
}(jQuery));

h1の見出し(#記号のやつ)をタイトルに設定する

// Add title
var titletext = $('h1:last').text();
document.title = titletext + " / catch.jp-memo" ; // 表示テキスト

外部リンクを別タブで開く。

// Add external link on a-tag
var domain = "www.example.jp/wiki/"; // 設置場所
$('a[href^=http]').not('[href*="'+domain+'"]').attr('target','_blank');

あと、こんな方法もあるみたい。

MDwikiコンテンツエリアのカスタマイズ | 3D技術研究所Blog

ライセンス

GPLv3 + 追加条項
追加条項は、GoogleマップのコードとかTwitterボタンとかは、GPLv3の対象外とか言っている(たぶん) -- https://github.com/Dynalon/mdwiki/blob/master/LICENSE.txt

類似ツール

Flat-FileCMS:https://www.google.co.jp/search?q=Flat-FileCMS&ie=utf-8&oe=utf-8&gfe_rd=cr&ei=TdmaWa3hK6fK8gfU6I7YBg
Markdown・Textile・Wiki記法をサポートしたJavaScript製ドキュメントフレームワーク「Invisible.js」を公開しました(オープンソース) | Chrome Life:http://www.chrome-life.com/javascript/554/
好きなブラウザで動作するMarkdownビューアlocal-notes.jsを公開しました http://henry.animeo.jp/blog/2013/11/29/local-notes-js/
marked.js https://github.com/chjj/marked

あと、MDwikiという名前のツールが、他にもいくつかあって、ちょっとまぎらわしい

erickrdch/mdwiki https://github.com/erickrdch/mdwiki
http://www.mdwiki.net/

catch.jp blog