Home

Awesome

BookPub - book publishing with web-driven tools

<p align="center"> <img src="assets/bookpub-logo.svg" width="70%" height="70%" alt="BookPub logo header"/> </p>

BookPub is an advanced book publishing framework for creating manuscripts in Markdown/HTML/CSS/Javascript, and publishing them into any format (PDF, ePub, MOBI, HTML, Print).

BookPub manages a manuscript-to-market toolchain, allowing publishing firms, authors and other stakeholders to manage one markdown-based manuscript source, which can be professionally designed and typeset (even for print) using HTML, CSS and Javascript Web Standards. Bookpub will build your manuscript into any format (PDF, EPUB, MOBI, HTML).

Features

  1. Markdown Based Manuscript

    • It's All Plain Text.

      Easy-to-read, easy-to-write using the industry standard, Markdown, for authoring content.

    • Lot's of Ready Made Apps/Tools.

      Because markdown is ubiquitous for authoring content, there are already loads of tools and apps out there. That said, you can use any plain text editor (or Code Editor)

    • Easy to Manage Edits & Versions.

      Because it's plain text, we can use the most robust versioning software out there. We recommend github.com, but you can use any versioning platform.

  2. Javascript Enabled With EJS

    • BookPub uses EJS (Embedded Javascript) Templating which means that the entire world of javascript is at your disposal:

      • Use conditionals to only render certain sections of your manuscript for certain formats (like pdf, epub, mobi, etc)

      • Use any NPM package or javascript library, to add a world of possibilities to your book

      • Use custom layouts and includes to reuse parts of your manuscript anywhere

Install

Prerequisites

Creating a New BookPub Project

Usage

We created BookPub in an effort to share an example of best-practices (or at least our opinion) for managing a manuscript-to-print pipeline. Rather than forcing people to follow rigid rules, we've attempted to provide a maximum of flexibility, while showing our example of the converntions that we use.

BookPub is essentially an HTML/CSS/Javascript based book framework. All the different book formats are built off of this foundation. That said, we've attempted to help streamline the process by integrating common industry tools and best-practices.

1. Getting Started

Your new book project will have the following structure:

my-book
  |- assets/                # Media assets (illustrator, photoshop, etc.)
  |- build/                 # Built book formats (pdf, html, epub)
  |- manuscript/            # Manuscript source
    |-- index.md.ejs        # Starting-point ("entryfile") for your manuscript
    |-- frontmatter/        # Frontmatter content (titlepage, preface, etc.)
    |-- mainmatter/         # Main content (chapters, etc.)
    |-- backmatter/         # Backmatter content (author's note, bibliography, index)
    |-- theme/              # Theme & Design elements
      |--- css/             # CSS for each format
      |--- js/              # Javascript files
      |--- media/           # Media & Artwork
      |--- fonts/           # Custom fonts
      |--- svgs/            # SVG files
  |- release-builds/        # Publicly released builds
  |- book.config.yml        # Meta and Config Data (ISBN, Title, etc.)
  |- CHANGELOG.md           # This is where you can describe the changes for each new version
  |- nodemon.js             # Nodemon config file (for Dev Mode) watches for (rebuilds) upon manuscript change (edit carefully)
  |- package.json           # Package config file
  |- README.md              # Documentation for Contributors
  |- webpack.config.js      # Webpack config file (for Dev Mode) reloads new builds into browser

2. Managing Your Book's Meta Data (book.config.yml)

The book.config.yml is a YAML File used to store your book's meta-data and configuration settings. You can use this file to store details about the book, like the title, isbn, author, lccn, etc.

All the data in book.config.yml is made available for you to use in the manuscript source.

For Example:

Let's say that we have the following book.config.yml file:

# book.yml

title: My Book Title
isbn-13: 012345678910

# (the rest of your meta data)

settings:
  entryfile: index.md.ejs

In your index.md.ejs you can access the book title using EJS syntax:

The title of my book is <%= meta.title %>.

Your build file will then be renderred as:

The title of my book is My Book Title.

3. Working With Your Manuscript

--> One Manuscript To Rule Them All <--

BookPub's philosophy stems from the DRY (Don't Repeat Yourself) principle. As such, we want to always/only have one manuscript from which all the formats are built.

You can arrange your manuscript in any way you like: One giant document, or a complicated breakout of different files and sections. We have tried to give users as much flexibility as possible.

That said, there are a few things to keep in mind:

--> THREE SIMPLE RULES <--

  1. All source code for your manuscript must be stored in the manuscript/ folder.

  2. All files must end with .ejs (except for files in the theme folder)

    • Our convention for naming files has been [name].[filetype].ejs.
      • e.g. So, if we had an html file, it would be named myname.html.ejs
    • For a tutorial on using EJS, visit the EJS Site

  3. The entryfile (the beginning of your manuscript) must be specified in your book.config.yml (entryfile).

    • We recommend keeping the first file as index.md.ejs

    • You can choose another name or location. But it must be specified in your book.config.yml

      For example, if you want your entryfile to be myentryfile.md.ejs, record it in your book.config.yml as:

      # book.config.yml

# Let's set our entryfile
settings:
  entryfile: myentryfile.md.ejs

  4. Ok, so maybe we lied...another small rule/recommendation concerning your theme folder.

    • Keep in mind, during the build process, your theme folder will be copied over as-is.
    • If you want to use SASS (.scss) to handle your css, you will need to keep the css as it is when your new book project is built. We will be changing this later, but for now, it's a requirement for SASS.

4. Building Your Book

The basic command for building a specific format (type) of your book is the following:

bookpub build -t [format-type]

  1. The HTML format of your book
  1. The Print-PDF version of your book

5. A Development Workflow

--> DEV MODE <--

We built the BookPub framework to make writing, designing, typesetting and formatting your book as streamlined and instantaneous as possible.

With DEV MODE, you can work in REAL TIME. Changes in your manuscript are rebuilt and reloaded in your browser in real time.

DEV MODE will launch a browser window that will display the newly built version of your book, which will be updated as changes are made to your manuscript.

HTML "DEV" Mode

To work on the HTML version of your book in "dev" mode, type:

bookpub dev -t html

Now, as you edit your manuscript, the final HTML build will automatically be reloaded into your browser with the new updates.

Developer Note:

  1. We are using Nodemon to watch for changes in your manuscript directory and build a new copy upon any change.

    • We have included your own nodemon.js file if you would like to make changes (tread carefully)

  2. We are using Webpack to serve any new builds to your browser and refresh when a new build is created.

    • We have included your own webpack.config.ejs if you would like to make changes (tread carefully)

PDF "DEV" MODE

To work on the PDF version of your book in "dev" mode, type:

bookpub dev -t pdf

6. Themes: Book Design & Typesetting

BookPub uses industry standard web technologies for the design and layout of your book: HTML, CSS(3), and Javascript.

We chose to use web standards for the design element because they are free, they are universal, they are flexible, and there is an unending supply of resources for learning and working with these standards.

Developer Note:

There is clearly a significant audience who prefer to write their books using tools like Pandoc and LaTex for print typesetting. In our experience, even though these tools are powerful, they also requiring a significant learning curve, and their implementation is difficult to say the least. Additionally, finding designers who can work with web standards is fairly universal and international.

Your Theme Folder

We have intentionally chosen to place all custom styling/fonts/media/etc. in the theme/ folder of your manuscript/ directory.

Developer Note:

You can actually use whatever structure/location you want. We decided to use the theme/ convention in order to allow a consistent way to drop new formatting/themes into your book by simply copying a new theme into your manuscript folder.

Styling with CSS or SASS

BookPub allows you to use Plain CSS (.css), or Sass CSS (*.scss) to style your html book.

7. Working With the Print-Ready PDF

We have chosen to use PrinceXML to create the PDF builds. In the future, we may also include the ability to use other pdf generators, but for now it's PrinceXML.

Please consult the princexml.com website for their documentation on building PDFs from HTML/CSS/Javascript

Developer Note:

PrinceXML is a pay-for-license and proprietary software, but they allow full use of their software. The only tradeoff for free use is the presence of a small logo/watermark on the very first page of any PDF that is generated.

You can also use Docusaurus (an online PDF generator that uses PrinceXML) as a pay-per-service version that uses PrinceXML.

Currently, PrinceXML seems to have the best PDF rendering engine, especially for advanced typesetting, using HTML/CSS3/Javascript. We will continue to explore other possibilities as we deem them sufficient in their feature-set.