@ig3/md2epub

Generate epub e-book files from Markdown files.

Install

$ npm install -g @ig3/md2epub

Generating an epub

Add 1 markdown file for each chapter (e.g. chap001.md, chap002.md, etc.).

Add images: cover.jpg for the book cover; chap001.md for an image to appear before the title of the first chapter (i.e. named the same as the chapter markdown but with an image extension), and any images referred to from the markdown files.

Run md2epub to convert the Markdown and images into an epub e-book.

metadata.json

md2epub gets meta-data from a file: metadata.json.

If there is no metadata.json, then md2epub will generate one.

You can edit metadata.json and re-run md2epub to regenerate the epub file with revised metadata.

The default metadata.json is:

{
  "title": "<the name of the folder containing the book>",
  "author": "Unknown",
  "language": "",
  "cover_image": "cover.jpg",
  "description": "",
  "tags": [],
  "source": "",
  "status": "",
  "modified": "<the current date>"
}

The title is the name of the directory in which md2epub was run.

epub book

md2epub creates an epub book from the files in the directory.

There should be one markdown file per chapter. Each markdown file is converted into an xhtml file and added to the epub, in lexical sort order. The chapter title is taken from the first top level heading in the file.

If there is a corresponding image file: an image file with the same name as the chapter markdown file but with extension jpg, jpeg or png, gif or webp, and this image file is not already included in the chapter, then it is added before the chapter title.

Configuration

Defaults can be set in:

• /etc/md2epub.json
• ~/.md2epub.json
• ~/.config/md2epub.json

For example:

{
  "defaultAuthor": "Ano Nymous",
  "defaultCover": "cover.png",
  "defaultDescription": "An epub from Markdown files",
  "defaultLanguage": "EN",
  "defaultTags": [
    "Private",
    "English"
  ],
  "defaultTitle": "An Untitled Work",
  "defaultVerbose": true
}

If multiple configuration files exist, they will be merged in the order they are listed above with values from the latter overriding former values.

Motivation

I wrote this for a fairly trivial reason: I was using pandoc to make epub books from Markdown files. It worked well enough but I wanted to put images before the first header of a chapter and I couldn't find an easy way to do that with pandoc. At each level 1 header it starts a new chapter. Anything and everything before a level 1 header is part of the preceding chapter(s). I may have been able to do it if I messed with the pandoc templates. I like the idea of using generic tools, but it seemed less work to write this.

The epub might not follow the epub v3 standard exactly, but Calibre finds no errors in them.

epub books I examined are simple. I didn't read the standard. I copied examples. A bit of XML composed by string concatenation. Some xhtml files (I wish it was HTML 5). And it works well enough for Calibre, Calibre-web and @ig3/calibre-web

I'm not publishing epub books. I'm composing them for my own use. It's an easy way to turn Markdown into epub that I can read in my browser.