search

FriendsOfEpub / Blitz

An eBook Framework (CSS + template)
http://friendsofepub.github.io/Blitz/
MIT License
217 stars 35 forks source link
blitz css ebook ebook-framework epub epub2 epub3 framework kindle

readme

Blitz logo

Blitz eBook Framework

An eBook framework (CSS + template) whose mantra is “finding simple solutions to complex issues.”

Important Note

All the Blitz repositories reached End Of Life on July 1, 2020. The entire project is no longer maintained and its repositories are read-only. You can still fork them if they can be useful to you.

Licence

Blitz is released under MIT Licence © 2016, Jiminy Panoz.

Support

How to Use

There are various ways to use blitz, from adding the available stylesheets (CSS folder) to building them with the LESS framework.

Use the Provided Stylesheets

You can either add blitz.css or an alternative stylesheet in your EPUB file.

blitz.css is commented but you’ll find an uncommented version in the AltStylesheets folder (which helps you save some 7kb).

In this folder, you’ll also find blitz-lite.css and blitz-reset.css (normal + minified).

  1. blitz-lite.css should be enough for simple books like novels and essays (it’s 3kb);
  2. blitz-reset.css is just… the reset we’ve designed (it’s 1kb).

Add styles on top of those two is up to you… But you’ll then miss the powerful tools we’ve built in LESS!

Install and Compile With npm

First go to the blitz root directory and install the dev dependencies: 

npm install

Then make your changes in LESS and run:

npm run build

This will compile the LESS src to the default, lite and reset stylesheets, and update the template.

If you want to compile only one stylesheet you can run:

All those sub-builds will generate uncommented/minified files as well.

Finally, to update the packaged EPUB file then use npm run make.

Compile LESS Sources Without npm

Either use the GUI or, if you’re one of the old-school type…

For Default

lessc Blitz_framework/LESS/blitz.less Blitz_framework/CSS/blitz.css

For Lite

lessc Blitz_framework/LESS/blitz-lite.less Blitz_framework/CSS/AltStylesheets/blitz-lite/blitz-lite.css

For Reset

lessc Blitz_framework/LESS/blitz-reset.less Blitz_framework/CSS/AltStylesheets/blitz-reset/blitz-reset.css

Related Blitz Tools

Design & Goals

Blitz was designed to deal with the significant obstacles a newcomer or even an experienced producer might encounter. Its major goals are:

  1. to be simple and robust enough;
  2. to offer a sensible default;
  3. to manage backwards compatibility (ePub 2.0.1 + mobi 7);
  4. to provide useful tools (LESS);
  5. to get around reading modes (night, sepia, etc.);
  6. to not disable user settings.

We have chosen a functional approach (FCSS) but LESS presets are planned to provide meaningful class names depending on eBook’s type (poetry, plays, etc.).

The 4 Principles of Blitz

  1. Espouse inheritance and the cascade, the 2 fundamental principles of CSS. eBooks are documents, CSS was designed for documents… It’s a match!
  2. Build and refine, don’t style and undo. Don’t override your own styles, create reusable components—the reset should help you do that.
  3. Don’t fight, skirt. Be smart, it’s not worth fighting RS’ default stylesheets (their selectors and !importants are too much hassle), trompe le monde.
  4. Have fun! We’ve done our utmost to help you avoid common pitfalls. You don’t have to deal with the crappiest parts of eBook CSS authoring, sit back and relax.

Useful Details

Blitz is leveraging the concept of inheritance. Values inherit and currentColor are being used extensively to make the framework compatible with Reading Systems’ default stylesheets, reading modes (color) and user settings (font-size, font-family, line-height, etc.).

Defaults and a reset do the heavy lifting so it’s just about building on top of this base. Please note Blitz is taking care of defaults RS aren’t necessarily (HTML5 block elements, hyphens and pagebreaks for selected elements, etc.).

Finally, although we try to rely on RS’ typefaces, typography has been fine tuned.

To sum up, we’ve tried to find a balance and feel like Blitz defaults can help producers get around a lot of possible issues: we don’t need hacks, we don’t have to change values in specific situations using complex media queries.

Related EPUB 3.1 issues

Browserlist we’re using for progressive enhancements

The following is a list of browsers/rendering engines modern EPUB apps are using behind the scenes. It is using the browserlist format and can be imported in websites such as CanIUse.

ie >= 11
edge >= 14
last 4 chrome major versions
safari >= 9.1
ios_saf >= 9.3
android >= 4.4
last 2 and_chr major versions

Alternatively, you can use this CanIuse Link.

When checking for support, you can simply click “Apply Filters” in order to display those browsers in the support table.

Some more details

Frequently Addressed Questions

Is this project still active?

Nope.

Blitz was sunset in 2020. As of July 1, 2020 the entire project is no longer maintained and its repositories read-only. You can still fork them.

We deemed Blitz feature-complete though, and it should consequently be still useful for a couple of years.

Has anyone funded this project?

Nope.

It grew organically out of the desire to learn CSS preprocessors, then improve at JavaScript and make Progressive Web Apps, etc. It just seemed that side projects sharing knowledge that would be useful to the ebook production community was the best way to achieve those goals.

At some point, sponsoring was considered but quickly dismissed due to the relatively small size of the ebook production community: it was simply too much to ask.

Which features did not make it into the framework?

Quite a lot, actually.

But maybe you could successfully build a business out of that list…

What is missing in version 1?

Better internationalization.

By improving support for the 24 additonal languages we added at some point, Blitz would better cover the needs and requirements of 3,049,150,507 speakers.

Why was JS abandoned?

JavaScript has quite a bad reputation in publishing, especially as Kindle and eReaders relying on Adobe’s RMSDK don’t support it. So it was not worth pursuing JavaScript exploration despite all the Research and Development that had gone into it.

A library of custom elements almost happened after successful initial testing, but one careful review later, it was clear most authors wouldn’t even bother trying such a library. That wasn’t a hill to die on when most authors want Reading Systems to handle that out of the box.

How to leverage the LESS meta-language?

Check this tutorial.

Log

1.5.2

1.5.1

1.5.0

With massive props to @ptmkenny for internationalization and config improvements.

1.4.1

1.4.0

1.3.0

1.2.4

1.2.3

1.2.2

1.2.1

1.2.0

1.1.3

1.1.2

1.1.1

1.1.0

1.0.1

0.9.5 (Pre-release) -> 1.0.0 (stable)