NAV
html css javascript

Introduction

Welcome to Bookiza’s official documentation. This site is also available as a superbook if you prefer to read on a tablet.

<!-- Paste at { ~/project/templates/body.html } -->

<div class="page flex">
  <div class="inner justify ">
    <h1> Hello world! </h1>
    <p> Lorem ipsum... </p>
  </div>
</div>  

/* Responsive layout and typography with viewport units */

@import url(https://fonts.googleapis.com/css?family=ABeeZee);

body {
  font: 6vw/1.0 'ABeeZee', sans-serif;
  overflow:hidden;
  background: white;
}

.page {
  height: 100vh;
  width: 80vw;
  margin: auto;
}

.inner {
  margin: 10vh auto;
  width: 100%;
  height:80vh;
}

.flex {
  display: -webkit-box;
  display: flex !important;
  align-items: center;
  justify-content: center;
}

.justify {
  text-align: justify;
}

/* Your custom styles below */

// JS inside book is way cool
console.log('Hello world');

Bookiza is a book reification framework that cuts down your book writing and publishing time by half. By half, no less. It lets you manage your manuscript smartly and bakes in all the goodness of the web into your book.

Go ahead, produce delightful books that work everywhere (See support.

On the right you’ll find some sample code (plain ol’ HTML, CSS and JS) that makes for scalable responsive books. Or sometimes, food for thought. 🍄

Setup

Machine

You’ll require a desktop with the following configuration:

OSes: Any

Users on Windows will also need to install a unixy-style shell interface like Powershell, Babun, Cmnder or Cygwin. Mac & linux have what is called the terminal app or the bash or the shell.

Memory

Minimum 2G RAM

Browser

Google Chrome, Mozilla Firefox, Apple Safari or MS Edge. Having older versions of IE alongside is also recommended for testing.

Installation

Install Nodejs

Recommended Node v6.2.0 or above.

It is recommended to install the latest stable (It’s FREE!) version of node (v6.2.0 as of writing this) directly from the Nodes.js® website.

Mac/ El Capitan

$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew update
$ brew doctor

$ brew install node 

Once node is installed check with $ node -v

On Mac it is generally recommended to install nodejs with Homebrew (Instructions on right).

Once your system is ready to brew, install node with

$ brew install node

Windows

Download the Windows installer and run the installer (the .msi file) in the previous step. Follow the prompts in the installer, accept the license agreement, click the NEXT button to accept the default installation settings.

Restart your computer.

Linux

Use package control to grab the appropriate node installer for your distribution of linux.

Once node is installed on your machine check its version with:

$ node -v


Install GIT

$ git --version
$ git version 2.10.1
$ brew install git      # Mac

$ sudo apt-get install git  # Ubuntu/Debian 

$ sudo yum install git-all  # Fedora

Configure git after installation with:

$ git config --global user.name "Your Full Name"

$ git config --global user.email "your@email.com"

Internally Bookiza utilizes git-scm to hook up your manuscript to a repository. While this is not mandatory, it is highly recommended to check-in your manuscript into a repository like Github or Bitbucket and back it up. You can use any other version control software if you like.

Mac / El Capitan

If you are using Mac, you may already have Git. To find out, open a terminal and enter git --version. If it’s not there already install with brew install git.

Or you can download the installer, double-click the dmg and complete its installation. After installation is completed configure Git global user.name and global user.email as shown on the right.

Windows

Download the Windows Installer Package for Git.

Run the installer on your computer to open Git Setup wizard and follow through all the steps to complete the installation. Once the installation has completed, open Bash.vbs inside the Git folder / Programs directory to open the command window.

Configure your Git global user.name and Git global user.email as shown on the right.

Linux / Ubuntu

On Ubuntu use the apt package management system or the command line utility apt-get (or optionally the graphical user interfaces like Synaptic or Aptitude) to install Git.

Upon completing installation make sure to configure Git global user.name and global user.email as shown alongside.


Install Bookiza

$ npm install bookiza -g

$ bookiza -v

1.0.1

$ bookiza --help        // See help/options/documentation

On your terminal run:

$ npm install bookiza -g

You’ll need to install bookiza and gulp globally. Once the installation has completed, check with $ bookiza --version.

Dependencies

async, superagent, progress, co-prompt, co, path, fs, chalk, commander, string, dateformat, shelljs, os-homedir

Registration

$ bookiza register      # Shortcut: $ b z  ## See $ b -h

Bookiza must be registered to be able to publish books online.

It comes pre-integrated with Bubblin’s POST & PATCH API so that you can easily deploy your books online with just one command: $ bookiza publish.

Learn more & sign up on Bubblin – a free hosting and rendering platform for superbooks – to get your api_key & bubblin credentials.

Use your credentials from Bubblin to register bookiza client. You’re all set.

Manual registration

$ touch .bookizarc      // At the root
$ vi .bookizarc         // Copy & paste the following JSON:

{
  "token": "",
  "username": "",
  "email": "",

  "mode": {
    "HTML": "html",
    "CSS": "css",
    "JS": "js",
    "HEAD": "html"
  },

  "urls": {
    "registrationURL": "https://bubbl.in/api/register",
    "baseURL": "https://bubbl.in/api/books/"
  }
}


You can also set the the api_key and user credentials manually.

On the root of your machine:

You’re all set.

Manuscript

$ bookiza new MY-AWESOME-BOOK -l 12 -t comics   # Creates project with 12 fresh leafs (24 pages) inside `manuscript/`.
$ cd MY-AWESOME-BOOK

$ bookiza server            # Opens http://localhost:4567 on your browser!

To initialize a new project (book, comics, magazine or blank) with exactly 2N number of pages pass the --leafs option with value N and a --template option if required. Like so:

$ bookiza new MY-AWESOME-BOOK-TITLE --leafs 2N --template comics where N is number of leafs.

Bookiza’s new command will set up your project, bootstrap the manuscript (leafs) along with necessary configurations and apply the layout template you passed along in the options (if any). Bookiza will also npm install all the dependencies your project will need, git initialize the project and then seek confirmation from you to check-it into Github.

Inside the manuscript/ folder you’ll find that 2N number of blank pages, the place where you’ll be spending maximum of your time writing.

Commands

$ bookiza --help

or 

$ b --help            # bookiza is aliased to `b`

Bookiza comes with several built-in methods to help you manage your manuscript better.

The keyword bookiza itself is aliased to the alphabet b to make it easy to call methods which are aliased further as per list below:

So a $ bookiza new MY-AWESOME-BOOK -l 12 can be shortened to $ b n MY-AWESOME-BOOK -l 12.

Command alias Arguments Options Description
new n projectName numberOfLeafs, templateName New book (Setup project)
add a - numberOfLeafs Add leaf(s) to the stack (End of book).
insert i insertAt numberOfLeafs Insert leaf(s) into the stack (In between book)
remove r - removeAt Remove page_at (Not leaf!) and append a blank one.
clip c - numberOfLeafs Clip leaf(s) off the stack.
length l - - Book length
publish p - - Publish book
server s - portNumber Start server
status - - - Check status
push - - - Push changes
update u - - Update bookiza
register z - username, passkey Register bookiza
whoami w - - WhoAmI registered as?
help h - - help

Templates

Bookiza comes along with several ready-to-use responsive and FREE templates so that writers don’t have to worry about the layouts or design. Pass the templateName option to bookiza new command (see above) to apply a layout you want.

Current templateName options are:

Feel free to contribute new templates from the stories you make, but ensure that those worked responsively everywhere. Or at least on as many devices as possible.

Afterthoughts

With mobile becoming a dominant way for people to consume web, Bookiza brings only the most natural form of reading experience that people have loved for over a millenium: Flipping pages.

Here are a few afterthoughts that will help you better understand how Bookiza work:

Preprocessors

Customize bookiza according to your taste, make your book stand apart. Bookiza comes in multiple flavors: HAML, PUG, markdown, SASS, LESS, Stylus etc.

There are two ways to configure bookiza for your book:

For example, this sample book uses .haml and .scss instead of plain html and css.

Configuring bookiza will set its generators and renderers to use the appropriate templating engine (or preprocessor) for its pages (and templates). You can also use a combination of preprocessors within the same book with a more complicated setup (discussed elsewhere).

By default Bookiza is configured for the native web i.e. plain HTML, CSS and JavaScript. The output of the build is always HTML, CSS and JavaScript as well no matter what preprocessor logic or transformations are applied beforehand.

Bubblin

Bubblin is a community of book lovers on the web. A marketplace for beautiful responsive books. Visit https://bubbl.in to learn more about its slew of web/marketplace specific features that may be relevant for your book.

Bookiza comes pre-integrated with Bubblin’s POST/PATCH API. This allows us to publish and update our works online easily with just one command: $ bookiza publish.

$ bookiza whoami

If you registered the bookiza client earlier but do not remember your credentials then try:

$ bookiza whoami command.