Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

175 lines (149 sloc) 4.689 kb


Pubgen is a command-line based epub generator. Make an epub with YAML.


$ # First, install Ruby and then
$ gem install pubgen


$ pubgen -h
pubgen 0.2.0, an epub generator. (

  pubgen <yaml file> [-o <epub file>] [-v]
  pubgen <yaml file> -m
  pubgen -t <toc file> <epub root path>

    -o, --output EPUB_FILE           Specify output epub file path
    -m, --meta-file-only             Generate .opf, .ncx, mimetype, ...
    -t, --toc TOC_FILE EPUB_ROOT     Print YAML using TOC file
    -v, --verbose                    Verbose output

Quick Start

Create an epub

Prepare files (documents, images, style sheets, etc.) that make up the publication. Apple's iBooks requires strict xhtml. tidy -asxhtml will be helpful to you.

$ find .

Make your files XHTML compatible.

$ cd contents
$ tidy -asxhtml x.html > a.html
$ tidy -asxhtml y.html > b.html

Create the utf-8 encoded YAML file describing the publication. As an example, will_oldham.yml.

# METADATA: Publication metadata (title, author, publisher, etc.).
# See
  title: "Will Oldham: Wikipedia, the free encyclopedia"
  creator: Wikipedia
  date: 2012
  language: en
  subject: American alternative country singers
  source: ""

# GUIDE: A set of references to fundamental structural features of the 
# publication, such as table of contents, foreword, bibliography, etc.
# See
# If you provide cover-image without cover-page, pubgen automatically 
# generates cover-page xhtml, and add it to manifest and spine.
  cover-image: images/cover.jpg

# MANIFEST: A list of files (documents, images, style sheets, etc.) that make 
# up the publication.
# See
# All the file paths in manifest ought to be relative to yaml's path and in the
# same or sub-directory of yaml file. Say yaml's path is /book/a.yaml.
# - a/b/c.html                # good. in the sub-directory
# - d.jpg                     # good. in the same directory
# - ./e.jpg                   # good. in the same directory
# - /a/b/c.html               # bad. in the different directory
# - ../d.png                  # bad. in the parent directory
# - /book/e.html              # bad. although in the same directory
# - ../book/f.png             # bad. although in the same directory
  - contents/a.html
  - contents/b.html
  - images/cover.jpg
  - images/1.jpg
  - images/2.jpg
  - images/3.jpg
  - style.css

# SPINE: An arrangement of documents providing a linear reading order.
# See
  - contents/a.html
  - contents/b.html

# TOC: Table of contents
# See
# Add a colon suffix to indent
  - 1 Music -- contents/a.html:
    - 1.1 Discography -- contents/a.html#discography: 
      - 1.1.1 Studio albums -- contents/a.html#studio_albums
    - 1.2 Response -- contents/a.html#response
  - 2 Film -- contents/b.html:
    - 2.1 Filmography -- contents/b.html#filmography
  - 3 Photography -- contents/b.html#photography
  - 4 References -- contents/b.html#references
  - 5 External links -- contents/b.html#external_links

Run pubgen.

$ pubgen <epub root>/will_oldham.yml -o out.epub
zip > out.epub


Create meta files

If you understand Open Packaging Format 2.0.1 spec, and want to edit some properties of the epub before packaging, you can try pubgen with --meta-file-only option.

$ cd <epub root>
$ pubgen will_oldham.yml -m
cat > META-INF/container.xml
cat > mimetype
cat > cover-pubgen.xhtml
cat > content.opf
cat > toc.ncx
# Edit content.opf/toc.ncx, and archive epub with zip command
$ zip -r ../will_oldham.epub .

Generate YAML using TOC file

Pubgen generates a YAML using TOC file. Pubgen-generated YAML is not complete, but is probably quite useful.

$ pubgen -t <epub root>/contents/toc.html <epub root> > out.yml
$ vi out.yml # Open and complete YAML
$ cp out.yml <epub root>
$ pubgen <epub root>/out.yml -o out.epub
zip > out.epub
Jump to Line
Something went wrong with that request. Please try again.