bookiza / bookiza.cli

The book reification framework for the web. Website →

Bookiza

This is the first part of the Bookiza Abelone library.

Publish and distribute your books via the web. 🥳

Bookiza is a book-making tool for the web. It is a lightweight javascript framework with a browser shim that lets you publish scalable and deeply formatted long-form works using traditional publishing values and modern web principles that sit above-the-fold.

Advantages

Print delightful digital books on the web that reach everyone, and not just those who own specialized expensive hardware to read your work.

Visit the Bookiza Website for more details.

Format

Bookiza uses the Superbook format to control the editions and compile your manuscript into a production-ready (SPA-like) book.

Support

Books created using Bookiza Abelone are supported on every major device, tablet, and desktop sporting a modern browser and an Internet connection.

Examples

Visit Bubblin Superbooks to view Books of different types with varying layouts, and features like intrinsic typesetting, line-tracking, and responsivity.

Recommended hardware

Despite ubiquity, we recommend tablets (any brand) in landscape mode to best experience our books.

Documentation

• Documentation is available here.
• A free book on The Bookiza Framework.

A quick primer on the Superbook format is available here.

What you'll need

node > 18.3.0, git-scm, an api_key from https://bubblin.io and a unixy-style bash.

Setup

$ npm install -g bookiza

You'll need to install bookiza and shelljs as global.

Check installation with:

$ bookiza --version

bookiza is shortened to alphabet b on your terminal as CLI invoker. This is useful when you're creating a relatively longer body of text and it becomes increasingly painful to type full form commands into the abyss.

Next, register Bookiza client with:

$ bookiza register or $ b z

Provide your Bubblin credentials to connect to its sweet POST API. You're all set!

To check:

$ bookiza whoami or $ b w

Getting started

To bootstrap new project, run:

$ bookiza new my-awesome-new-book --leafs 40 --template novella
# Creates a project with 40 fresh leafs (80 pages) inside the `manuscript/` folder and applies the responsive `novella` template on it with initial defaults.

cd into the project and:

$ bookiza server                  # Open https://localhost:4567 on your browser!

Full vocabulary is available with:

$ bookiza --help

That's it.

Layout Templates

Bookiza comes along with several FREE, responsive and scalable templates so that you don’t have to do the layouts yourself.

Feel free to fork and build new templates to kickstart your work in any way you like.

We accept new templates for different kinds of books and formatting options. PRs and new ideas are welcome.

Advanced Configuration

Bookiza and Bubblin default to using only the building blocks of the web i.e. HTML, CSS & JavaScript. Bubblin maintains only the head version of your clean and compiled manuscript to render your work. No history is maintained at Bubblin at this time.

Preprocessors

Bookiza lets you compose your manuscript with any preprocessor you like. There are two ways to configure Bookiza so as to cater to your needs depending on the type of content on your book.

ArcBookiza or just the Arc

Configuring Bookiza is very simple and its editing modes can be easily customized to suit your needs by setting the mode according to your liking.

When you register the Bookiza client (with $ bookiza register) in your local, it will automatically create and configure the following runcom file .bookizarc at the root of your machine. You can set the processing modes of Bookiza on this arc file and Bookiza will automatically pick up the desired processing mode for your manuscripts.

# $ vi .bookizarc

{
  // ...
  "mode": {
    "HTML": "html",   # markdown, haml, or pug etc.
    "CSS": "css",
    "JS": "js",
    "HEAD": "html"
  },
  // ...

}

See full list of templating engines & preprocessors that are currently available.

ArcBook or just the book

Editing mode can also be set on per book basis using the .bookrc configuration at the root of your project:

# $ vi .bookrc

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

In case of conflict between modes on .bookrc and .bookizarc the book level configuration i.e. via .bookrc shall prevail.

PR Conventions

• PR branches must work everywhere: i.e. should have been tested manually on all browsers and all operating systems i.e. MacOS, Windows, and at least one distribution of Linux.
• Commit messages must be self explanatory. Please do pepper your submissions with comments!
• Provide system related information of the dev machine (OS/Browser/Screen) you developed your PR on.

LICENSE

TBD. UNLICENSED

bookiza.cli's Issues

Make it a self-updating terminal CLI

Hook up terminal start / bash start event to check upgrades on bookiza and upgrade if set to true. Somethings like ncu, ncu -u or as discussed here: http://stackoverflow.com/questions/35485250/how-to-make-a-self-updating-node-package

$ bookiza add -l 4 command fails inside empty manuscript.

Steps to reproduce:

1. $ cd project/manuscript && rm -rf *
2. $ cd ..
3. $ bookiza add -l 4
   [ error in console ]

Installation problems

I encountered some ambiguities and errors in installation instructions

1. Instructions to install prerequisites don't specify whether they must be OS installed or npm installed.

• git & gulp seem to need to be OS installed (apt, yum)
• shelljs seems be an npm install
• OS installing Node seems to force later npm global install to require sudo. Using nvm seems like a better way to install Node

2. Neither sudo apt install git-scm nor npm install -g git-scm work at all. What is it?

3. bookiza --version does not work (bookiza --VERSION does)

4. Xubuntu 20.04 has done away with python2, so it also should be listed as a prerequisite.

5. Then, showstopper bug apparently ...

Error: Node Sass does not yet support your current environment: Linux 64-bit with Unsupported runtime (88)
For more information on which environments are supported please see:
https://github.com/sass/node-sass/releases/tag/v4.13.1
    at module.exports (/home/erpdev/bookiza/bookiza.book/node_modules/node-sass/lib/binding.js:13:13)
    at Object.<anonymous> (/home/erpdev/bookiza/bookiza.book/node_modules/node-sass/lib/index.js:14:35)
    at Module._compile (node:internal/modules/cjs/loader:1102:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1131:10)
    at Module.load (node:internal/modules/cjs/loader:967:32)
    at Function.Module._load (node:internal/modules/cjs/loader:807:14)
    at Module.require (node:internal/modules/cjs/loader:991:19)
    at require (node:internal/modules/cjs/helpers:92:18)
    at Object.<anonymous> (/home/erpdev/bookiza/bookiza.book/node_modules/gulp-sass/index.js:162:21)
    at Module._compile (node:internal/modules/cjs/loader:1102:14)

but, in fact it was due to assuming nvm install node and nvm use node. Prerequisites should not specify simply Node >=8.11.3, instead it should be 8.11.2 < Node < 15. So ... nvm install 14 and nvm use 14, did work.

6. With all the above solved, I have an apparently working "Heidi" book ... but then:

• With Chrome (Version 86.0.4240.183) the front cover appears and a pulsating right vertical arrow bar. Clicking the bar causes the book to turn to the next page, spread to 100% browser width and then refuse to respond to any further event from keyboard or mouse.
• With FireFox 83.0 it is possible to turn pages with the pulsating right and left vertical arrow bars, but nothing else works.

7. template types, such as novella, magazine etc are suggested, but there is no documentation to give any idea what might be the differences and relative advantages of each one.

What is the license?

You say your MIT license is "dormant" and real license is TBD. It makes it really hard to consider investing time in all this tech when the licensing is up in the air.

Upload cover and banner art from the project repository over to Cloudinary.

Upload assets/images over to Cloudinary using clientside user credentials provided by the developer.

missing crust folder with its gulpfile when creating book

Hi

I was trying to update bookiza from 0.0.1 (or 0.0.11) and i noticed i had to update node aswell. After doing that i installed bookiza 0.1.1. That went well without errors. I then tried to add a new book, but then i got the following errors below.

I'm running nvm 0.33.2 with nodejs at version 7.10.0
Gulp is at 3.9.1 and npm is 4.2.0

Error:

$ bookiza new mybook20 --leafs 12
Initializing… [ manuscript=mybook20 | leafs=12 | template=blank ]
Copying crust failed Error: ENOENT: no such file or directory, lstat '/Users/Dieuwert/.nvm/versions/node/v7.10.0/lib/node_modules/bookiza/crust'
License.txt… :added.
README initialization… :success.
.gitignoring /build /node_modules… :done.
Applying a blank layout… :success.
Arcvalues & Package Json unavailable Error: Did not find the arc!
Failed. Gulpfile unavailable. Error: ENOENT: no such file or directory, link 'crust/gulpfile.js' -> 'gulpfile.js'

I'm missing out on a crust folder and a gulpfile, compared to the book that i had from an older bookiza version. What can i do to see the book running with "bookiza server" locally? Right now it won't run.

Use 'First Five Pages' to structure set up book types and default templating.

Pick up formatting ideas and initial codex structuring from the First Five Pages by Noah Lukeman. Manual steps no more! ❤️

Error when running bookiza server. NPM warning when installed gulp-haml and more

One of the problems I faced when using it in cmd ( I am using Windows) is that 'gulp-haml' package is using a very old lodash package which made the installation stuck at ' installing npm modules...: Successful' with errors. I fixed it by upgrading the lodash package inside gulp-haml but I am not sure whether I have finish downloaded whole framework. IMG here (https://drive.google.com/open?id=0B9UG5fu2lrPxNzJ3MzVoWVREa2ZsbHNoSmppQjk1cHNiVjk0)

Next, I ran 'bookiza server' command in cmd, and I got and error saying it is unable to get page-1.html and so on as shown in
IMG(https://drive.google.com/open?id=0B9UG5fu2lrPxbEl0TDJGMXkxeDdvX1FaSkVLekFLbjdiMHdF).
I copy pasted HTML pages from https://github.com/bookiza/bookiza.js/tree/master/html/renders
inside my build/renders directory. But I was unable to achieve swipe effect as shown in video in the Google drive link below.
https://drive.google.com/file/d/169EQj0Cs0DNFBL2UGIGETcPoC0VSHxpg/view?usp=drivesdk

I also encountered some bugs when pressing the next indicator as shown in this Google drive link
https://drive.google.com/file/d/16I-iecFMrBfVpgpd-sTiISTtNjAlr6YU/view?usp=drivesdk

Another bug is that the last page mixed with the first page and the position of the book shifted to the right side as shown in this Google drive link
https://drive.google.com/file/d/16JJmetvJ4m60QG4WVdEYOn3wz8mE1xtw/view?usp=drivesdk

I also wanted to use it on my own domain which I couldn't find how in the docs.

Ensure semver and formatted commits.

It is hard enough to commit with proper messaging let alone guarantee semver and elaborate changelogs manually. Use semantic-version and commitizen to ensure good habits.

Prevent text reflow trigger on safari/webkit

vw/vh based text scaling is buggy on Safari/webkit lowering quality of line-tracking and strong format-ability.

Partial upgrade done with following caveats

1. All commands except new were commented out for the time being.
2. The new command works until this line

(TBD: We can choose to modify the arc-bookiza dependency or drop it from the requirements of the project.)

CLI guidelines.

https://clig.dev/

Trouble installing latest version

Thanks for getting back to me! My email bounced, so I figured it’d be easier to make an issue here.

Installing Attempts

I checked the version of bookiza that I installed from npm, and it was, indeed, out of date.

Installing with NPM from Github

I tried npm installing from the github URL, I received the following errors when making a sample book from scratch (the bookiza -v reported: 1.0.0-semver-ized):

bookiza new MY-AWESOME-BOOK-V3 --leafs 12 --template comics

Initializing… [ manuscript=MY-AWESOME-BOOK-V3 | leafs=12 | template=comics ] Copying crust failed Error: ENOENT: no such file or directory, lstat '/usr/local/lib/node_modules/bookiza/crust' Failed to create subdirectories… Error: EEXIST: file already exists, mkdir 'assets/css' License.txt… :added. .gitignoring /build /node_modules… :done. README initialization… :success. Applying a comics layout… :success. Arcvalues & Package Json unavailable Error: Did not find the arc! Failed. Gulpfile unavailable. Error: ENOENT: no such file or directory, link 'crust/gulpfile.js' -> 'gulpfile.js'

Installing GitHub master downloaded as a local package with npm

I downloaded the bookiza zip from github and npm installed it locally, after which I replaced the alias in my global modules with the unzipped folder (the bookiza -v reported: 1.0.0-semver-ized). Unfortunately, I still had this error when creating a new book:

bookiza new MY-AWESOME-BOOK-V6 --leafs 12 --template comics

Initializing… [ manuscript=MY-AWESOME-BOOK-V6 | leafs=12 | template=comics ] .gitignoring /build /node_modules… :done. README initialization… :success. License.txt… :added. Applying a comics layout… :success. Mobilizing crust… :success. Arcvalues & Package Json unavailable Error: Did not find the arc! Server setup… :complete.

Other Troubleshooting

Unfortunately, the bookiza server fails to run. Then, I realized that it didn’t actually create any pages (even though 12 was specified when creating it).

I tried adding pages, but it threw an error requiring a .bookrc file. I was able to add and configure the file, but bookiza server still failed. After comparing my generated booklet to the bookiza framework example, I realized I did not have a package json in my root (and thus no node modules), and that my crust folder was completely empty. And then I gave up debugging.

Other Questions

Looking at the .bookrc example in the readme, I was just wondering what other options are available.

Would the below json be valid? What exactly is the HEAD key and what does it do? What other options are there for HTML, CSS, JS, and HEAD?

{ "mode": { "HTML": "markdown", "CSS": "scss", "JS": "babel", "HEAD": "html" } }

Similarly, how do templates work?

What does command bookiza push do, and how is it compare to bookiza publish and bookiza server?

I’m glad the page proportions are so close. That’ll help a bunch. Resizing 40 * 6 pages would not be fun. Unfortunately, the magazine I’m working is not on github nor open source. I’d have to get the school’s permission after summer ends. I’ll try again to get it working.

Not watching style.scss files for changes

Bookiza server doesn't reload when changes are made to .scss files. The watch list is probably missing the extension in the watchList.

Impossible to handle page turn events

I have place the following JS code on each page, from the cover page through to page 13, with incrementing numbers for each respective page:

window.addEventListener('load', (event) => {
  console.log('Page 1 loaded');
});

window.addEventListener('pagehide', (event) => {
  console.log('Page 1 gone');
});

If I click on Edit Draft of my book, the Cover page opens and the browser console shows:

Page 3 loaded
Page 5 loaded
Page 6 loaded
Page 2 loaded
Page 4 loaded
Page 1 loaded

When I turn to pgs 2 & 3, the console shows:

Page 2 loaded

to pgs 4 & 5

Page 7 loaded
Page 1 gone
Page 4 loaded

to pgs 6 & 7

Page 8 loaded
Page 2 gone
Page 3 gone
Page 6 loaded
Page 9 loaded

to pgs 8 & 9

Page 11 loaded
Page 4 gone
Page 5 gone
Page 10 loaded
Page 8 loaded

to pgs 10 & 11

Page 13 loaded
Page 12 loaded
Page 6 gone
Page 7 gone
Page 10 loaded

---

Question:
How can my JS code know that it's page is open so that it can run and closed so that it should stop?

Validate length of subtitle before post/patch to Bubblin.

Check if length of subtitle string is less than 60 characters.