ASP.NET Webサイト上で Markdown な .md ファイルを表示する

はじめに - Markdown とは?

Markdown とは、Wiki などで用いられるような、軽量マークアップ言語である。
Markdown 書式で記述した内容を、なんらかのプロセッサに読み込ませて、結果として HTML を生成してブラウザに表示、なんていう用途で使われたりする。

たとえば、Markdown 記法で記述した下記のようなテキスト(文字列)を、

# This is Heder-Level1

- List Item-A.

- List Item-B.

しかるべき Markdown プロセッサを通せば、

<h1>This is Heder-Level1</h1>

<ul>

<li>List Item-A.</li>

<li>List Item-B.</li>

</ul>

なんていう HTML が手に入る寸法だ。

.NET Framework 環境においても、この Markdown のプロセッサライブラリが公開されている。
有名どころとしては、MarkdownSharp や、MarkdownDeep などがあるらしい。

...ところで ASP.NET Web API の "help page" について

さてとろこでちょっと話は変わるが、このブログでも度々取り上げている
ASP.NET Web API について。

まさしく "Web で API を公開する" にはうってつけのこの機能。
しかし、少なくともβ段階の現時点では、"help page" 生成は実装されていない。

"help page" とは、すなわち、API の使い方についてのドキュメントだ。
API コントローラクラスを .NET のリフレクション機能で実行時に動的に探索したり、XML ドキュメントコメントを解析すれば、APIの一覧、引数、説明文などを掲載した Web ページを自動生成できるはず、というわけだ。

下記ブログに "今はまだ" 実装してないよ、的なことが書かれているっぽい。

Will ASP.NET Web API support a test client and help page generation?
http://blogs.msdn.com/b/bryang/archive/2012/02/21/asp-net-web-api.aspx

なおすでに、多少のコードを自分で配線して、help page を自作する話題がブログ投稿されている。

ASP.NET Web API: Generating a Web API help page using ApiExplorer
http://blogs.msdn.com/b/yaohuang1/archive/2012/05/21/asp-net-web-api-generating-a-web-api-help-page-using-apiexplorer.aspx

...で、それと Markdown の関係は?

話が長くなってしまったが、実装・公開した ASP.NET Web API サイトに、その Web API の使い方・ドキュメントを掲載しようと思ったの発端。

上記のような全自動 help page を自作搭載してもよかったのだが、もしかしたらリリース時点では ASP.NET 本家本体による help page サポートが実装されるかもしれない。

取り急ぎ、Markdown でちゃっちゃっとドキュメント書いて公開できれば、それでいいのに、と考えたわけだ。

いちおう、MarkdownSharp はじめ、公開されているライブラリを使えば、たとえば .cshtml ファイル中で、

@Html.Raw(new Markdown.Transform(markdownText))

みたいな記述をすれば、Markdown 記法で書かれたテキストをHTMLに変換して出力することはできる。

しかし、今回は完全に静的なテキストを書きたいだけなのだ。

結論を言えば、
拡張子 .md で Markdown 記法で内容記述したテキストファイルを置いておくだけで、ブラウザでその .md ファイルを指す URL を開けば、HTML に変換された結果で表示されたらうれしいのに、
と思ったのである。

Markdown Pages!

...ということで、NuGet パッケージマネージャの検索結果を眺めていたら、
Markdown Pages というパッケージを発見。

試しにこのパッケージをインストールしてみたところ、これが大正解!

.md ファイルを置いておけば、これが Markdown 記法であると解釈されて、ブラウザには HTML に変換された結果が返るのだ。

ちなみに、ASP.NET Web Pages の仕組みに則ってページハンドラが実装されているため、拡張子 .md を省略した URL でもアクセス可能である。

すなわち、http://host/foo.md が表示できるのであれば、http://host/foo でも同じコンテンツが表示される。

※拡張子 .markdown に対しても同じく処理される。

ということで Markdown Pages を自サイトに導入させて頂き、目的は達成、一件落着。

NuGet Docs で使われてます

どうやらこの Markdown Pages は、
NuGet Docs サイト (http://docs.nuget.org/) で使うために開発されたっぽい。

実際、NuGet Docs サイト上の任意のページに対して、ブラウザのアドレスバーから、拡張子 .markdown を明示的に付けてアクセスしても、ちゃんと同じコンテンツが返ってくる。

ソースコードを拝見すると、恐ろしく高度なことがかかれているわけではなく、基本的には、.md コンテンツを読み取って、MarkdownSharp を使って Transform する、WebPage クラスから派生したクラスの実装である。
しかし、細かいところのチューニングがそこかしこに効いている。

http://docs.nuget.org/ 用には、この Markdown Pages パッケージに対してさらに、専用のカスタムコードやカスタムチューニングが施されているようだ。

いずれにせよ、このような形で NuGet パッケージとして公開してくださっているのは大変ありがたいことである。

お陰で、.md に対するハンドラを自作するという "車輪の再発明" をすることなく速攻で .md でコンテンツ公開できたのである。

多謝。