grunt-mdeb

mach3/grunt-mdeb @ GitHub
Grunt task to publish markdown docs as EPUB 3.0 book.

Markdown書類とJSONの設定ファイルからEPUBデータを作成します。 ナビゲーションドキュメント（論理目次＋視覚目次）はMarkdownを元に出力されるXHTMLから抽出されて自動的に生成されます。 名前の「mdeb」は「Markdown to eBook」の略です。

動作環境

タスクの中でシェルコマンドを叩いている箇所があるので、 bash等が動く環境でないと動作しません。 Mac OSX や Linux なら問題ありませんが、 Windowsの場合は Git CUI（MinGW）や cygwin 環境で使用する必要があります。 Git CUI は msysgit で Git 環境を導入していれば同梱されているのでお勧めです。

• Git for Windows
• MinGW | Minimalist GNU for Windows（Git CUIの中身です）
• Cygwin

デモ兼ドキュメント

ドキュメントは grunt-mdeb のリポジトリの「demo」の中に document.epub として保存されています。 これは実際に mdeb タスクで生成された EPUB データです。 変換される前の Markdown は demo/src に、EPUBデータにコンパイルされる前の XHTML データは demo/dest/tmp に格納されています。

• demo/src （Markdownデータ）
• demo/dest/tmp （XHTMLデータ）

基本的な使い方

1. インストール

npm でタスクをインストールします。

$ npm install grunt-mdeb

2. タスクの設定

Gruntfile.js で “grunt-mdeb” を読み込み、”mdeb” タスクを設定します。

grunt.loadNpmTasks("grunt-mdeb");

grunt.initConfig({
    mdeb: {
        dist: {
            options: {},
            src: "src",
            dest: "dest"
        }
    }
});

src と dest は必須項目で、それぞれ元データと出力データの格納ディレクトリを指定します。 options は任意でオプションを設定してください。

3. データ構成

src ディレクトリの中に元データを格納していきますが、次のような構成にします。 （各ディレクトリの名前は先述のオプションで変更する事ができます）

src/
├ assets/
├ data/
│ ├ cover.md
│ ├ 01.md
│ ├ 02.md
│ └ ...
└ publish.json

data ディレクトリにはコンテンツの元になる Markdown 書類を格納します。 assets ディレクトリにはスタイルシートや画像などの依存ファイルを格納します。 assets ディレクトリの中身は全て複製されて EPUB データに同梱されます。

4. publish.json

publish.json には、タイトルや著者名をはじめ、EPUBデータを構成する為の情報を全て記述します。

{
    "meta": {
        "name": "document",
        "title": "My First Book",
        "author": "mach3",
        ...
    },
    "assets": {
        "coverImage": "assets/img/cover.jpg",
        "commonStyle": "assets/css/common.css",
        ...
    },
    "items": [
        "data/cover.md",
        "data/01.md",
        "data/02.md"
        ...
    ]
}

中のデータは３つのセクションにわかれています。

• meta
  
  書籍の基本的な情報を格納する
• assets
  
  画像やスタイルシート等の情報を格納する
• items
  
  コンテンツドキュメントの元となる Markdown ドキュメントを列挙する

items の一番最初のドキュメントは表紙ページとして扱われる点にご注意ください。 項目のさらなる詳細やサンプルは ドキュメント に記してあります。

5. コンパイルする

mdeb タスクを実行して EPUB ファイルを生成します。

$ grunt mdeb

コンパイルに成功すると、dest ディレクトリの中に生成した EPUB データと、EPUB に固める直前のデータが格納されています。

dest/
├ tmp/
│ ├ OEBPS/
│ ├ META-INF/
│ └ mimetype
└ document.epub

注意点

• 
  

  中のシェルスクリプトには rm -r なども含まれているので、使用にはご注意ください。 コンパイルを開始する前に dest ディレクトリ内の *.epub ファイルと temp ディレクトリの中全てを削除してクリーンな状態にする様になっています。

  
  
• 
  

  一応バリデーションは通るように書かれていますが、あまり盲信せずに一応確認するようにしましょう。 オプション で、 コンパイル完了時に epubcheck を実行する事も出来るようになっています。 （別途 epubcheck のインストールが必要です）

  
  
• 
  

  grunt-mdeb を使用して被ったいかなる損害についても、対応はいたしかねます。

  
  

まとめ

私は物を書くときにいつも Markdown だったので、 そのまま EPUB に出来たら楽だろうな、と思って作ってみたパッケージです。 ブログを Markdown で書かれている方も多いと思うので、 何かの役に立つことがあれば。

追記

2014/02/13

サンプルコードの initConfig の中身が間違っていたので修正