Markdown記法を使ってプロジェクトの関連文書生成を効率的にする

Markdownって何ですか？

Markdownとは、John Gruberさんによって作られたマークアップ言語で、記述したテキストファイルをスクリプトで処理して二次生成物としてHTML出力する事ができます。
最近ではリポジトリに設置する文書にMarkdown記法を用いるケースを多く見るようになりました。
「README.mdって何だ？」っていうアレです。

今回はUOS-LPC800プロジェクトにおけるMarkdownの活用をご紹介します。

UOS-LPC800におけるMarkdownの活用

http://cubeatsystems.com/firmware/uos-lpc800/index.html

UOS-LPC800では、プロジェクト開始当初からMarkdownで一次文書を構成し、二次生成物としてウェブ用ファイルを作ることを考えていました。

Markdownのファイルをダウンロードすると変換用のPerlスクリプトが同梱されています。
Markdown.plを使用した事のある人にはわかるかもしれませんが、このスクリプトは単に書かれた事を書かれたように変換するだけのスクリプトです。

UOS-LPC800のウェブページを作るにあたって、Markfileやシェルスクリプトでラッパーを作りました。
これにより

1. Markdown記法でテキストファイルを記述
2. 端末でmake

するだけでウェブブラウザが開いて生成物の内容を確認できるようになります。

今回のラッパーでは以下を実現しています。

• ページで使用する画像はimagesに置いておけば良い。
• ページで使用するリソースはresourcesに置いておけば良い。
• Markdown.plで処理されないヘッダの類はhead.htmlとtail.htmlで付与する。

とこんな感じです。

ダウンロード

今回のファイル一式をこちらからダウンロードできるようにしておきました。