MarkdownからPDFやEPUBを生成するドキュメントツールCheepubのご紹介

1ファイルのMarkdownからPDFやEPUBを生成するドキュメントツール、Cheepubというツールを作りました。

• Cheepub: https://github.com/takahashim/cheepub

特徴

一言で言えば「MarkdownでRe:VIEWみたいなことを簡単にやりたい！」という人のための、Re:VIEWの劣化版（機能限定版）みたいなやつです。

• 設定ファイルを別に作ったり、Markdownファイルを複数に分割したりせず、1ファイルだけで完結します
  • Jekyllのfrontmatterみたいなやつで、YAML的な設定を書けます
  • ベージ分割はhorizontal line(HTMLで言うところの<hr />)の拡張で対応しています
• PDF生成にはLaTeXを使っていて、標準で縦書き・2段組に対応します
  • front-matterでいろいろ書けばできます。styファイルはなくてもよいです
• Markdownパーサにはkramdownを使っていて、若干の拡張があります
  • ルビ、縦中横、脚注などが追加されています（でんでんマークダウンぽいです）
  • 表については左右両側にpipe |を書くタイプの拡張です（pipeじゃない表は記法が衝突して死んだので）
• タイトルページ、奥付も生成可能です
  • EPUBのスタイルは適当なのでもうちょっとなんとかしたいですね……
  • 表紙画像は未対応です
• Re:VIEW記法ならサポートされている便利機能はごっそり落としています
  • 章番号、節番号は自動生成されません。Markdownなので。それぞれ手で書きましょう。連番が変わったときには手で直しましょう。
  • 図表番号も自動生成されません。というか図表のキャプションもありません。Markdownではみんな書かないみたいなので。図のキャプションはそのうちできるかも。
  • 目次も（今のところ）生成されません。これはそのうち対応するかも。
  • この辺のやつが使いたい場合には、素直にRe:VIEWを使うことをおすすめします。

インストール

CheepubはRubyのgemとして実装されているので、gemコマンドでインストールします。対応しているRubyのバージョンは2.5.xですが、2.3くらいでも動きそうな気がします。

$ gem install cheepub

PDFの生成にはLaTeXが必要です。対応しているのはupLaTeXとLuaLaTeXです。どちらかをインストールしてください。おすすめはTeX Liveのインストールです。

使い方

Cheepubはコマンドラインで使うことを想定しています。

1. Markdownで文書をもりもり書く、あるいはMarkdownで書かれた文書を持ってくる

2. 必要に応じてメタデータと章分割の記述を追加する

3. 以下のようにcheepubコマンドを叩くと、book.epubというEPUBファイルが生成される

$ cheepub sample.md

また、以下のように--latexオプションをつけると、book.pdfというPDFファイルが生成される

$ cheepub --latex sample.md

その他細かい挙動の変更には以下のコマンドラインオプションやfront-matterの設定を記述します。

コマンドラインオプション

• --title 【タイトル】 タイトルを指定します。
• --author 【著者名】 著者名を指定します。
• --config 【設定ファイル】 後述のfront-matterに相当するYAMLファイルを別ファイルで与えた場合に使います。Markdownファイル内に設定を書きたくない人用です。
• --latex LaTeX経由でPDFを出力します。
• --debug デバッグモードにします。
• --out 【出力Fファイル名】 (または -o 【出力ファイル名】) 出力するEPUBファイル名またはPDFファイル名を指定します。省略時はbook.epubまたはbook.pdfになります。
• --[no-]titlepage タイトルページを出力します。no-がついていると出力しません。
• --page-direction 【方向】 ページ方向を指定します。ltr か rtlにします。
• --json デバッグ用に、Markdownを解析した結果のAST(JSON)を出力して終了します。普通は使わないんじゃないかと思います。
• --help ヘルプを表示します。
• --version バージョンを表示します。

front-matterがない場合は--titleと--authorは必須です。

CheepubのMarkdownについて

基本方針は3つです。

• 「（コマンドラインで使える）でんでんマークダウンみたいなやつ」が目標
  • 「簡単にEPUBが作りたい」（ただしコマンドラインで）という人向けツールです
  • しかしなぜかPDFまで出力できるようになってしまった…（kramdownがLaTeX吐けたので、これならできるかも？と思って頑張ったらできてしまった、という経緯です）
• あまり頑張らない
  • 「でんでんマークダウン完全互換」とかは大変そうなので、簡単に実装できる範囲でやる
  • kramdownをベースにするので、でんでんマークダウンになくてもkramdownにある記法等は動くことはあるかも
• CLIでの使いやすさを重視
  • ブラウザでぽちぽち指定するのはめんどくさい（ユーザとしても実装者としても）
  • なので、Jekyllのfront-matter的なものを導入しました。1ファイルで設定コミで完結しているのがポイントです

作者としてはろすさんリスペクトなので、でんでんマークダウンがそのまま使いたい！　という人は素直にでんでんコンバーターを使うことを強くおすすめします。

でんでんマークダウンとの互換性を高めるPull Requestをいただいても「ここまで頑張るのはちょっと…」という場合にはrejectさせていただくかもしれません。ご了承下さい。

なお、細かい説明を読むよりサンプルを見た方が早い、という方はsamplesをご覧ください。

改ページ（ファイル分割）

でんでんマークダウン由来です。「半角のイコール記号 = が3つ以上で構成される行があると、その前後でHTMLファイルを分割します。」というやつです。前後の空行を忘れないようにしてください。

それとは別に、-が6つ以上の場合は改ページにする、という拡張も追加しました。-が3つから5つまでの場合はMarkdownのまま<hr />になるので、書き分けができます。この仕様はそのうち変更するかもしれません。

縦中横

これもでんでんマークダウン由来です。平成^30^年みたいに書くと、縦書きでも「30」が横に並びます。
ただし、縦中横が使える文字はいわゆるASCIIの文字（のうち^以外）に限定しています。この限定はなくてもよかったかもしれません。

脚注

これはでんでんマークダウンというよりはkramdownの機能をそのまま使っています。

ルビ

これはでんでんマークダウンのルビの縮小版です。グループルビだけ対応しています。

パラグラフへのclass属性の指定

これはkramdownの拡張機能で、{: .foo}のような行を追加すると<p>...</p>要素にclass属性を追加できます。

PDF(LaTeX)では今のところほとんど使いみちがない（単に無視される）のですが、右寄せ({: .text-right})だけは対応しています。

{: .text-right}
この行は右寄せになります。

Cheepubのfront-matterについて

でんでんコンバーターの設定ファイルは設定ファイルとMarkdownファイルを別々に渡す方式でしたが、せっかくなのでJykellのようなfront-matterを使えば1ファイルにまとめられるのでは……？　ということで、---が先頭に来れば次の---までをYAML形式の設定ファイルとして切り出すようにしてみました。

設定する内容については、でんでんコンバーターを参考にしようかとも思ったのですが、なんか複雑そうだったので思い切りシンプルなものにしてしまっています。

サンプルのMarkdownファイルをsamplesディレクトリに置いてあります。こちらを参考にしてください。

設定項目

title

本のタイトルを指定します。現状は1個しか指定できません。

省略は不可です。

author

本の著者を指定します。EPUB3だとcreatorですね。

省略は不可です。

id

本のID、identifierを指定します。現状1個だけです。そのうち必要があれば複数個指定できるようにしますが、ベタに内容を指定する方式のみにすると思います（でんでんコンバーターのidentifier-typeみたいなものは設けない）。

省略時にはUUIDを自動生成します。またPDF(LaTeX)では使われません。

date

出版日を指定します。省略時には現在日時が登録されます。

PDF(LaTeX)では使われません。

lastModified

最終更新日時を指定します。省略時には現在日時が登録されます。

PDF(LaTeX)では使われません。

pageDirection

ページの送り方向を指定します。横書きならltr、縦書きならrtlにします。

省略時は設定自体が省略されます。

colophon

奥付を指定します。

奥付は、タイトル以外は個別に指定します。JSONのobject(keyとvalue)で項目名と項目値を記述します。

※現在はauthorの値と奥付の著者名は連動していません。検討の結果、奥付の表は項目名も含めて自動生成しないようにしています。著者名も別途記述してください。

colophon_before, colophon_after

奥付の表の前後に出力する文言を指定します。

一般的には、colophon_beforeは版・刷・バージョンごとの出版履歴、colophon_afterは著作権情報などを記述することを想定しています。が、別に制限はされていません。

また、現状は（まだ）Markdownでは記述できません（記法は単に無視されます）。改行は改行として使われます。

実装について

Markdownのパースにはkramdown、EPUBの生成にはgepub、PDF(LaTeX)の生成にはrb_latexなどのライブラリを使用しています。

refinementsを使ってみたのでRuby 1.9とかでは動きません。もう2018年ですし、もう少し新し目のRubyをインストールしていただきたいところです（2018年5月現在、2.2系以前のRubyは公式メンテナンスが終了しています）。