Skip to content

Latest commit

 

History

History
296 lines (180 loc) · 14 KB

README.md

File metadata and controls

296 lines (180 loc) · 14 KB
Raw

BookPub - book publishing with web-driven tools

BookPub logo header

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

  • Automatic Conversion of quotes and en/em-dashes

    • Using Smartypants, all quotes and en/em-dashes will be automatically converted to curly (left/right) quotes and the relevant UTF-8 Codes/Typeset for en/em-dashes

  • Multiple Formats

    • Formats currently supported: PDF-ebook, PDF-print, HTML

    • Coming very soon (epub, mobi, and more)

Install

Prerequisites

  • NodeJS - You will need to have a working install of Node.js (which will include NPM) in order to use BookPub. There are two options:

    • NodeJS Installer

      If you don't plan to use NodeJS outside of using BookPub, we recommend using the NodeJS Installer by visiting their download page and selecting the installer for your operating system.

    • NVM (Node Version Manager)

      If you plan on using NodeJS in other contexts, we recommend using NVM (NodeJS Version Manager). It is far more robust and flexible. You can visit the NVM Github page for detailed instructions. But generally it can be installed using the following command:

      curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

  • PrinceXML - You will need to install PrinceXML to build PDFs

    We've chosen the PrinceXML library because it is the best available for converting HTML/CSS/Javascript to Print-Ready PDFs. (At some point we may add other options.)

Creating a New BookPub Project

  • From the command line, type:

    npx create-bookpub-project

    If this is your first time, please select (y) when prompted.

    This will install BookPub (globally) on your system. You will then be asked a series of questions to help setup your new project.

    This is an example book to demonstrate how to use HTML/CSS/Javascript to publish a book. It's built off of the example Boom! microformat here. The answers to your npx create-bookpub-project will be used to fill in the title, author, etc.

  • Test Drive - You can test drive your new project by changing into your new project cd [your-project] and creating a basic HTML format of your example book:

    bookpub build -t html

    This will build the HTML format of your new book.

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

  • All that is needed to build the HTML format of your book is to type this command in your project's home directory:

    bookpub build -t html

    This will build your manuscript into an HTML version of your book, located in the build/html/ folder.

  1. The Print-PDF version of your book

  • To build a pdf typeset version of your book for print, type this command in your project's root directory:

    bookpub build -t pdf

    This will build your manuscript into a print-ready PDF version of your book in the build/pdf/ folder.

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

  • This will create two builds

    • The index.html file

      This will be loaded into the browser automatically and will use the styles.pdf.css and theme for the book. Like in the HTML Dev Mode, as you edit your manuscript source code, both the index.html file and the index.pdf will be rebuilt. The index.html will be reloaded into your browser automatically.

    • The index.pdf file

      This will need to be manually loaded into your own choice for PDF viewer. Generally speaking, your PDF viewer will reload the index.pdf file each time it is built (whenever you edit the manuscript source code).

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.

  • If you change your .css files to .scss, BookPub will use Sass to build your CSS prior to its use in the build process (More information about SASS)

  • We recommend using a new stylesheet for each format

    • This allows you to create a conditional statement in your index.md.ejs file, that loads a stylesheet based upon the output type (format). So if you are building your HTML format, the styles.html.scss file will be used.

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.