IISにMDwikiをホストする

小規模でお手軽な、できれば「Markdownで文章書いてアップして終わり」くらいお手軽なWikiサーバーが欲しくなり、いろいろ探してみたところMDwikiが良さそうだったので導入して試してみました。

github.com

このMDwikiは基本的にはローカル環境での利用が想定されている様ですが、IISでホストする手順も公式に用意されています。

Set up MDwiki on IIS Server

環境構築はこの手順に従うだけですが、本エントリでは私自身の備忘も兼ねて少し補足を入れながら説明していきます。
また本エントリの手順をまとめたものをGistに上げています。

MDwikiをIISにホストするスクリプト · GitHub

導入環境

最新のWindows Updateを適用したWindows Server 2016で行います。
手順自体は簡単ですので、Windows Server 2012 R2など他のバージョンでも問題なく導入できるでしょう。

サイトはデフォルトのDefault Web Siteを使う想定です。

IISのインストール

Install-WindowsFeatureでIISの機能を追加します。
MDwikiは静的なサイトですのでASP.NETなどの機能は無くても構いません。

本エントリではWEBサーバーの機能とIIS 管理コンソールを追加しておきます。

# IISのインストール
Install-WindowsFeature Web-WebServer, Web-Mgmt-Console

IISの設定変更

MDwikiをIISでホストするにはMarkdownファイル(拡張子.md)に対するMIMEの設定を変更する必要があります。
公式の手順にある様に管理コンソールからGUIで行っても構いませんが、ここではAdd-WebConfigurationで設定します。

$SITE_PATH = 'MACHINE/WEBROOT/APPHOST/Default Web Site'

# MIME設定の変更
$mime = Get-WebConfiguration -PSPath $SITE_PATH -Filter system.webServer/staticContent/mimeMap | Where-Object { $_.fileExtension -eq '.md' }
if($null -eq $mime) {
    Add-WebConfiguration -PSPath $SITE_PATH -Filter system.webServer/staticContent -Value @{fileExtension='.md'; mimeType='text/x-markdown'}
}

MDwikiのダウンロードとインストール

MDwikiは公開しているサイトのルートにmdwiki-latest.html(mdwiki-latest-debug.html)に配置するだけでインストールできます。
ここではInvoke-WebRequestを使ってindex.htmlという名前で保存します。

$SITE_ROOT = 'C:\inetpub\wwwroot'

# なぜかVer.0.6.2だとデバッグ版でしか動かない
#Invoke-WebRequest -Uri http://dynalon.github.io/mdwiki/mdwiki-latest.html -OutFile (Join-Path $SITE_ROOT 'index.html')
Invoke-WebRequest -Uri http://dynalon.github.io/mdwiki/mdwiki-latest-debug.html -OutFile (Join-Path $SITE_ROOT 'index.html')

上記コメントにも記載していますが、現在の最新版であるVer.0.6.2ではリリース版であるmdwiki-latest.htmlだと上手く動作しなかったため、デバッグ版であるmdwiki-latest-debug.htmlをダウンロードする様にしています。

初期ファイル

MDwikiのインストール自体はこれで完了ですが、最低限Wikiを動作させるには以下のファイルを作っておく必要があります。

index.md : ルートとなるMarkdownファイル
navigation.md : Wikiのページ上部にあるメニューを定義するファイル
config.json : MDwiki本体の設定ファイル

設定の詳細はドキュメントを参照してください。

今回は以下のスクリプトで各ファイルを生成します。

# その他最低限の初期ファイルを追加
@"
My MDwiki Website
----------------
### Hello World!
"@ | Set-Content -LiteralPath (Join-Path $SITE_ROOT 'index.md') -Encoding UTF8
@"
# My MDwiki
[gimmick:theme](flatly)
[Top](index.md)
[gimmick:themechooser](Choose theme)
"@ | Set-Content -LiteralPath (Join-Path $SITE_ROOT 'navigation.md')  -Encoding UTF8
@"
{
  "title": "My MDwiki"
}
"@ | Set-Content -LiteralPath (Join-Path $SITE_ROOT 'config.json')  -Encoding UTF8

なお各ファイルのエンコーディングは必ずUTF-8にしてください。

ここまで実行すると下図の様にWikiが動作するはずです。

f:id:stknohg:20180517183210p:plain

MDwikiの運用について

導入したMDwikiの運用について気になった点や、現在こんな運用をしているという点を紹介します。

IE対応

今回イントラネットにWikiを公開したのですが、IEでアクセスする場合、イントラネット内だとIEの互換モードでレンダリングを行おうとして表示に失敗してしまいました。
このためindex.htmlのヘッダに以下の記述を追記して互換モードをオフにする様にカスタマイズすることで対処しています。

<meta http-equiv="X-UA-Compatible" content="IE=edge" >

ギミック

MDwiki独自の機能としてギミックと呼ばれる機能があり、このうちAlertsギミックは便利でよく使っています。

シンタックスハイライト

現在のバージョンではコードのシンタックスハイライト機能にバグがあり、特定の言語に対するシンタックスハイライトを使うとブラウザがフリーズしてしまいます。

https://github.com/Dynalon/mdwiki/issues/328

私もいろいろ試してみましたが、コードのシンタックスハイライト機能は一切使わないのが良いと判断して運用しています。
(とても残念ですが仕方ない...)

コンテンツの更新

コンテンツであるMarkdownの更新はいろいろな方法で可能ですが、私はサイトのルートディレクトリを共有フォルダにしてMarkdownファイルを直接メンテナンスする方式を採りました。
かなりの暴挙なのですが、小規模であることとお手軽さを考慮してこうしました。実際めちゃくちゃ楽です。

バックアップ

MDwikiのバックアップはコンテンツを丸ごとコピーするだけで良いので非常に楽です。
環境依存な部分が多いのでスクリプトは公開しませんが、サイトのルートディレクトリをCompress-ArchiveでまるっとZip圧縮してバックアップ先に保存する運用をしています。

MDwikiの今後について

ちょっと理由は不明なのですが、去年の年末よりMDwikiのGitHubの更新が途絶えておりプロジェクトの今後に不安がよぎります。

ツール自体は現状でも便利に利用できますが長期の運用を検討しているのであれば少し様子を見た方が良いかもしれません。
いっそのことフォークして完全に自前で更新していくのもアリでしょう。

最後に

ざっとMDwikiの導入と運用について説明しました。
プロジェクトの今後に少し不安がよぎるものの、お手軽に導入、運用できるのでとりあえず試してみると良いでしょう。