markdown to ePub

OS X 10.10, pandoc 1.13.1

前にUPしたePubでソースコードのシンタックスハイライトを行う記事は、あれはあれでお手軽なやり方として悪くないとは思うのだが、SigilでePubドキュメントを作成するというのは、必ずしも効率の良い手段ではない。


Sigilがもう少しマトモなら良いのだが、アンドゥが1回しかない上、クラッシュする頻度が高すぎて、長時間のドキュメンテーション作業に使うにはちょっと怖いものがある。そもそもHTMLタグを直接書かなければならない時点でだいぶ効率が悪い。


今回は、もう少し効率の良いドキュメンテーション戦略の1つとして、マークダウン記法からePubドキュメントを作成するやり方を記載しておく。


【準備】
ドキュメントの変換ツールとして、pandocというものを使う。

http://johnmacfarlane.net/pandoc/installing.html

ダウンロード、インストールしておく。

この辺で、

http://kojika17.com/2013/01/starting-markdown.html
http://mametanuki.hateblo.jp/entry/2012/09/22/MarkdownList

マークダウンテキストの基本的な記述方法を学んでおく。


【ドキュメント作成】
サンプルとして、以下のようなマークダウンテキストファイルを作成してみた。

test.md

えいち1
========

えいち2
--------

### えいち3 ###

* 箇条書き
* 箇条書き
* 箇条書き


*斜体*
**太字**
`背景`


【リンク】
[ゆーえぬけーぴっつぁの日記] [1]


【ぶろっくくぉと】

> 引用できます。引用します。
> 
> 誰々さんがこんなこと言ってましたよ。
> あーだこーだ


【言語指定なしソースコード】

~~~
function test() {
  console.log("notice the blank line before this function?");
}
~~~


【言語指定ありソースコード】

~~~ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
~~~


【算数】

$$
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right) 
$$


【画像埋め込み】

![](pd_eclipse.jpg "Image Title")


[1]: http://d.hatena.ne.jp/unk_pizza/


スタイルシートを用意】
cssは自前で用意しても良いが、クイックスタートとしては、githubのスタイルあたりをお借りしてきて、必要に応じて自分でカスタマイズするのが良いかと。

https://gist.github.com/andyferra/2554919

今回は、↑これをそのままgithub.cssとして使用する。



【表紙】
必要ならば、カバーページ用の画像ファイルを用意しておく。今回は、cover.pngというファイルを用意したと仮定する。



【タイトルページ】
title.txtというファイルを用意する。

title.txt

% My Ebook Title
% Author

この情報はタイトルページ(カバーページの次のページ、目次の手前のページ)として使われる。
ドキュメントのタイトルと著者を記載しておくとよい。


【メタ情報】
ドキュメントにメタ情報を含めるならば、metadata.xmlを用意する。
少なくとも、ドキュメントを日本語で作成するならば、languageは指定しておいた方が良い。

metadata.xml

<dc:title>My Ebook Title</dc:title> 
<dc:language>ja</dc:language> 
<dc:publisher>Pizza Publishing</dc:publisher>
<dc:date opf:event="publication">2014-11-16</dc:date>
<dc:rights>Copyright 〓2014 by unk_pizza</dc:rights>

【変換コマンド】
以上で準備完了。
コンソールから変換コマンドを実行する。

pandoc -t epub3 -o test.epub title.txt test.md --epub-cover-image=cover.png --epub-stylesheet=github.css --epub-metadata=metadata.xml


こんな感じに仕上がった。

ちなみに、埋め込み画像のテストとして表示している画像(写真)は、Public Domainからお借りしてきたものであり、私の著作物ではないし、誰のものでもない。



いくつかのファイルを用意する手順が少々面倒臭いと思うかもしれないが、cssやらメタ情報は1度準備しておけば、多少の変更で使い回しが利く。変換コマンドは長いので、シェルスクリプトを用意しておくのが良いだろう。実際の作業のほとんどは.mdファイルを記述することになる。マークダウン記法でのドキュメンテーション作業は、マークアップランゲージで記述する場合に比べて、遥かに効率的である。

また、今回は最終的にePubドキュメントを作成したが、pandocは、HTMLやLaTeX、PDF形式への変換もサポートしている。その上、シンタックスハイライトもしてくれるし、さんすうの式の記述もサポートしている。大変強力なツールである。



おしまい