Madowu, MArkDOWn to markUp

Ippei Kishida

Last-modified:2017/10/16 07:05:03.

「まどう」と読みます。

Markdown で書かれたドキュメントを、 ヘッダフッタ付きのちゃんとした HTML にします。

1 インストール

gem install madowu

2 提供コマンド

2.1 madowu

一つの md ファイルを受け取り、 拡張子を html に変更したファイルを生成します。 元々存在しても、確認なしに上書きします。

madowu *.md のように 複数ファイルを一度に扱えるようにはしていません。 今のところ、これは make や rake が分担すべき仕事だと考えています。

madowu -h

でヘルプが出ます。

2.1.1 HTML head の title 要素

HTML ではファイルで表現される文書のタイトルを head 要素の title 要素で指定しますが、 native markdown ではこれを指定する方法がありません。 Madowu では、pandoc スタイルのタイトル指定があれば、ここからタイトルを取得します。

2.1.2 -o オプション, outline を埋め込む

見出しをまとめた outline を body の先頭に埋め込みます。 markdown 処理されたマークアップテキストに、さらにアンカーとリンクを追加します。

スタイルシートを適切に準備しておけば幸せになれるでしょう。 example/madowu.css を参考にされると良いでしょう。 また、一度 example で rake を実行し、 ブラウザで生成された html 群を見てみると良いと思います。

2.1.3 -O オプション, タイトル行そのものをその行へのリンクにする。

-o の機能に追加して、タイトル行そのものをその行へのリンクにします。

2.1.4 -d オプション, sidebar にディレクトリマップを埋め込む

ファイルが存在するディレクトリ周囲のファイルへのリンクをまとめ、sidebar に配置します。

親ディレクトリ、同一ディレクトリ内のエントリの2種類に分類します。 ディレクトリへのリンクに関しては、index.html or index.md があれば index.html へのリンクを作り、存在しなければ ディレクトリ自体にリンクします。 同一ディレクトリのファイルは、foo.mdfoo.html になるものとして、html の名前でリンクを生成します。 また、md もしくは html ファイルでタイトル相当の情報があれば、 これを 括弧内で補助的に表示します。

これも、 スタイルシートを適切に準備しておけば幸せになれるでしょう。

2.1.5 -c オプション, css ファイル指定

html 表示に適用するスタイルシートのパスを指定します。 元となる markdown ファイルのパスと指定された css ファイルのパスとの 相対パスに変換して埋め込みます。

2.1.6 -C オプション, charset 指定

HTML ヘッダで指定するファイルの文字エンコーディングを指定します。 指定しない場合のデフォルト値は US-ASCII です。

2.1.7 -s オプション

サイドバーに埋め込む内容のファイルを指定します。 このファイルを Markdown 処理して埋め込みます。

2.1.8 -m オプション

使用する markdown コマンドを指定します。 方言を含む markdown like な処理系を指定することも可能です。

2.2 tex2image

LaTeX の出力を画像にします。 数式の貼り込みなどに便利だと思います。 デフォルトでは png 形式で書き出します。

2.3 dirmap

親子関係で隣接したディレクトリへのリンクを表す .dirmap.md ファイルを Markdown 形式で書き出します。

.dirmap.md と内容に変更がなければ書き出さず、タイムスタンプを維持します。

2.4 mdcat

複数の md ファイルを結合して1つの md ファイルにします。 それぞれの md ファイルのタイトルをレベル1ヘッダー(#) にし、 元々のヘッダーはレベルを1つ落とします。

md ファイル内の外部ファイルへのパス(リンク、画像読み込みなど)を カレントディレクトリからの相対パスに変更します。

mdcat *.md
mdcat *.md --title="タイトル"

3 example

ウェブサイトのように、ディレクトリ丸々 markdown から html に変換するような場合に 使える Rakefile のサンプルが example/ 以下にあります。 とりあえず rake して生成される index.html と 他の html を見るとだいたい感じがつかめると思います。

4 関連プログラム

freestyle wiki からのデータ移動を考えている方は、 tefil に同梱してある fswiki2md が少し便利かもしれません。