Blitz’ documentation

Before proceeding further, let us make it clear that you might not need Blitz.

Using a framework implies trade-offs and it’s up to you to make sure you’ll get something in return. We know our default approach and reliance on LESS could be an issue for some people, so we’ll be perfectly fine if you decide not to use Blitz; we simply hope you could learn a thing or two.

CSS

A functional CSS approach has been chosen for the blitz’ style sheet. Think of classes as tools describing how elements should be laid out and typeset.

While following this functional approach is perfectly fine, we encourage you to use and extend the LESS’ meta-language to build your own templates, especially if you want to enforce semantic styling.

Reset

The blitz’ framework is built upon an eBook-specific reset.

It’s a sanitized fundation providing CSS authors with many benefits, including backwards-compatibility for HTML5 block elements, fixes for very specific bugs in some Reading Systems and making sure user settings are not accidentally disabled.

block-elements {
  margin: 0;
  padding: 0;
  font-size: 1em;
  line-height: inherit;
  text-indent: 0;
  font-style: normal;
  font-weight: normal;
}

html5-block-elements {
  display: block;
}

headings {
  text-align: left;
}

epub3-toc-list {
  list-style: none !important;
}

epub3-landmarks-pagelist {
  display: none;
}

inline-elements {
  font-size: inherit;
  vertical-align: baseline;
  font-style: inherit;
  font-weight: inherit;
  color: inherit;
  text-decoration: none;
}

Default template

Blitz’ stylesheet ships with a sensible default you can customize. It takes care of macro- and microtypography, figures and images, lists, context breaks, tables, code and medias.

Typesetting

.sans

Defines the Reading System’s default sans-serif typeface should be used for the element.

.serif

Defines the Reading System’s default serif typeface should be used for the element.

.monospace

Defines the Reading System’s default monospace typeface should be used for the element.

.humanist

Defines a humanist font-stack based on Myriad Pro for the element.

.geometric

Defines a geometric font-stack based on Futura for the element.

.oldstyle

Defines a modern font-stack based on Minion Pro for the element.

.modern

Defines an oldstyle font-stack based on Slab typefaces explicitly designed with ebooks in mind for the element.

.no-hyphens

Disables hyphenation for the element.

.justified

Applies full justification to the element and enables automatic hyphenation.

.align-[left|center|right]

Applies text-align to the element.

You must pick left, center or right alignment. Please note text-indent is reset for center and right.

.no-indent

Resets text-indent for the element.

.indent

Applies a text-indent of 1em to the element.

.hanging-indent

Applies an hanging indent to the element.

A left margin compensates for the negative indent.

.fs-[xxs|xs|s|m|l|xl|xxl|jumbo]

Applies a font size to the element. Line heights are also defined in order to keep vertical rhythm.

You must pick the size from xxs to jumbo.

.caption

Designed for images’ caption.

Hyphenation is disabled, indent is reset, line height compensates for a slightly smaller font size.

.footnote

Designed for footnotes/endnotes.

Indent is reset, line height compensates for a slightly smaller font size.

.bold

Applies bold to the element.

It should not be used in replacement of semantic tags.

.italic

Applies italic to the element.

It should not be used in replacement of semantic tags.

.bold-italic

Applies bold and italic to the element.

.small-caps

Sets the element to small capitals.

.caps-to-small-caps

Applies text-transform: lowercase to the element then sets it to small capitals.

.underline

Applies an underline decoration to the element.

.line-through

Applies a line-through decoration to the element.

Layout

.block

Sets the element to display:block.

.inline-block

Sets the element to display:inline-block (a block element sitting on a line).

.hidden

Sets the element to display:none (an hidden element whose dimensions are ignored).

.clear(-[left|right])

Allows to clear floats, which can be useful when floating several elements on the same page (e.g. book covers in a catalogue at the end of your eBook) or floating an element in a wrapper with a border.

By default, it clears both sides but it can be suffixed with left and right if needed.

.boxed

Applies a border and padding to an element.

.no-margin(-[top|bottom|left|right])

Resets the element’s margin to 0.

By default, it resets all margins but it can be suffixed with top, bottom, left or right if needed.

.margin-top-[s|m|l|xl|xxl]

Applies a top margin to the element.

You must pick a size for the margin, from s (half the line-height) to xxl (4 times the line-height).

.margin-bottom-[s|m|l|xl|xxl]

Applies a bottom margin to the element.

You must pick a size for the margin, from s (half the line-height) to xxl (4 times the line-height).

.margin-left-[s|m|l|xl|xxl]

Applies a left margin to the element.

You must pick a size for the margin, from s (half the default margin) to xxl (3 times the default margin).

.margin-right-[s|m|l|xl|xxl]

Applies a right margin to the element.

You must pick a size for the margin, from s (half the default margin) to xxl (3 times the default margin).

.w-[10→100]

Applies a width (%) to the element.

You must pick the width, whose values are counted in tens.

.h-[10→100]

Applies an height (%) to the element.

You must pick the height, whose values are counted in tens.

.wrap-[10→100]

Applies a width (%), centers the element and applies vertical margins (1 line-height) to the element.

You must pick the width, whose values are counted in tens.

.float-[left|right]

Floats the element and applies a small margin on the opposite side of the float.

You must pick the side of the float, either left or right.

.break-[before|after|inside]

Applies a page break.

You must declare whether this page break should occur before, after or inside the element.

.no-break-[before|after|inside]

Prevents a page break.

You must declare whether this page break should be avoided before, after or inside the element.

Scoped classes

table.table-fixed

Sets table-layout:fixed to the table.

You must then define a width for each cell in the first row of the table or else it won’t work as you may expect.

img.portrait

Sizes the image based on its height e.g. inline cover images.

The default value is 100%.

hr.transition

Turns the horizontal rule into a blank line (thematic break).

hr.asterism

Turns the horizontal rule into an asterism (context change).

The file asterism.svg should be embedded in your EPUB file in order for this class to work as expected.

LESS CSS

The LESS part of the Blitz framework has been designed as a meta-language for laying out and typesetting eBooks. If needed, an introductory tutorial is available.

All CSS classes, excepted the scoped ones, can be used as mixins in the LESS meta-language.

Please note there are extra mixins you can use in LESS.

How to customize

  1. Configure the output in blitz.less.
  2. Change variables in core/variables.less.
  3. Typeset your eBook in base/typo.less.
  4. Customize files in base, extensions and plugins if needed.

Variables

Variables can be found in core/variables.less. They allow you to customize your template.

@handle-kindle

A flag (boolean) to instruct Blitz whether it should output Kindle-specific adjustments using Kindle’s proprietary Media Queries or not.

Default is true.

@body-font-size

The font-size, in pixels, which will be used as a reference for the typographic scale.

Default is 16.

@min-line-height

The minimum line-height, as a ratio, which will be used as a reference for Kindle, superscript and subscript

Default is 1.2, which was the minimum value Kindle has historically supported.

@body-line-height

The line-height, as a ratio, which will be used as a reference for vertical rhythm.

Default is 1.5.

@scale-factor

The typographic scale which will be used for computing font sizes.

Five presets have been carefully chosen for eBooks: @unison, @minor-second, @major-second (default), @minor-third and @major-second.

@header-font-family

The font-stack which will be used for the selector set for @header-font-selector.

Default is inherit but will be ignored if @header-font-selector is set to undefined.

@header-font-selector

The CSS selector to which @header-font-family should be applied.

Default is undefined.

@asterism-path

The relative path to asterism.svg in your EPUB file.

@step

The margin, as a percentage, which will be used as a reference for the horizontal grid.

@primary-color

The first accentuation color.

By default, it is used for links.

@secondary-color

The second accentuation color.

By default, it is not used.

@link-color

The first accentuation color.

By default, it is used for links.

@border-width

The width, in pixels, which will be used as a reference for borders (e.g. table and boxed content).

Default is 1.

@border-style

The style which will be used for borders.

Default is solid.

@border-color

The color which will be used for borders.

Default is currentColor i.e. the color of the element.

@ul-type

The list-style-type which will be used for unorganized lists.

Default is disc.

@ul-type-nested

The list-style-type which will be used for nested unorganized lists.

Default is square.

@ul-type-position

The list-style-position which will be used for unorganized lists.

Default is outside.

@ol-type

The list-style-type which will be used for organized lists.

Default is decimal.

@ol-type-nested

The list-style-type which will be used for nested organized lists.

Default is lower-roman.

@ol-type-position

The list-style-position which will be used for organized lists.

Default is outside.

Typography Mixins

.fs(@font-scale)

Computes a font-size and a line-height for the element.

The @font-scale argument must be an integer (zero, positive or negative) telling which step in the typographic scale the element should use.

.rhythm(@font-scale, @margin-top, @margin-bottom)

Computes a font-size, a line-height and vertical margins for the element. Unlike .fs(@font-scale), it enforces vertical rhythm.

The @font-scale argument must be an integer (zero, positive or negative) telling which step in the typographic scale the element should use.

The @margin-top and @margin-bottom arguments can be an integer or a decimal (zero or positive) telling the number of lines which should be used for those margins.

.disable-hyphens

Disables hyphenation. It may come in handy for headings, centered elements, etc.

.manual-hyphens

Enables hyphenation and sets the value to manual. Reading Systems which support this will hyphenate text according to the soft hyphens (a.k.a. ­ or ­) you added in HTML files.

.hyphens-auto

Enables hyphenation and sets the value to auto so that Reading Systems which support hyphenation automatically deal with it.

.hyphenate

Basically, this is .hyphens-auto on steroids.

It enables automatic hyphenation and defines the consecutive numbers of lines, the minimum number of characters, the limit zone and how the last line should behave.

Parametric mixins are available in reference/hyphens.less for all those extra declarations.

.override-italic

Resets font-style to normal.

It should be used for italics nested in italics.

.override-iBooks-links(@overrideColor)

Enforces iBooks won’t override your links’ color in night modes.

Please note it is almost impossible to find a color which will provide good contrast in all modes.

.override-iBooks-locale(@lang)

This declaration can help with a font fallback and text-transform when the element is in another language.

The @lang argument should conform to ISO 639-1.

Please note iBooks and Reading Systems based on WebKit will automatically map this CSS property to the xml:lang or lang attributes it finds in your HTML files. You should not use it in replacement of those attributes.

.override-tab-size(@tabs)

Defines the number of spaces a tab should be in preformatted text.

Default is 4.

.override-ul-type(@ulType)

Removes list-style-type and reimplements a custom type for unorganized lists using a :before pseudo-element.

The @ulType argument should be the HEX value of the character.

.override-ol-type()

Removes list-style-type and reimplements increments for organized lists using a :before pseudo-element.

Please note you should customize the value for content.

Layout mixins

.width-center(@elWidth)

Computes left and right margins to center an element based on the declared width.

The @elWidth argument should be a percentage.

.border-radius(@radius)

Applies border-radius to the element.

Default is 5px.

.linear-gradient(@origin, @start, @stop)

Applies a linear gradient background with a background-color fallback.

Since linear gradients are treated as background images, they won’t be overridden in night modes.

Internationalization mixins

The Internationalization mixins are all static but not output by default, they are only referenced in the LESS Framework, and you must explicitly use them in a custom build.

Those mixins provide layout and typographic options, mainly for vertical writing, as well as tentative font-stacks for 24 additional languages. They should be considered experimental – don’t hesitate to report issues and/or help improve Blitz’ i18n.

.horizontal-tb

Applies horizontal writing, from top to bottom and left to right, to the element.

.vertical-lr

Applies vertical writing, from top to bottom and left to right, to the element.

.vertical-rl

Applies vertical writing, from top to bottom and right to left, to the element.

.text-orientation-mixed

Rotates the characters of horizontal scripts 90° clockwise. Lays out the characters of vertical scripts naturally.

.text-orientation-upright

Lays out the characters of horizontal scripts naturally (upright), as well as the glyphs for vertical scripts.

.text-orientation-sideways

Causes characters to be laid out as they would be horizontally, but with the whole line rotated 90° clockwise.

.line-break-auto

Breaks text using the default line break rule.

.line-break-loose

Breaks text using the least restrictive line break rule. Typically used for short lines, such as in newspapers.

.line-break-normal

Breaks text using the most common line break rule.

.line-break-strict

Breaks text using the most stringent line break rule.

.word-break-normal

Uses the default line break rule.

.word-break-all

Inserts word breaks between any two characters (excluding Chinese/Japanese/Korean text) to prevent overflow.

.word-keep-all

Prevents word breaks for Chinese/Japanese/Korean (CJK) text. Sets non-CJK text to normal.

.hanging-punc

Hangs a stop or comma at the end of a line if it does not otherwise fit prior to justification.

.emphasis-filled-sesame

Uses filled sesame as the emphasis mark.

.emphasis-open-sesame

Uses open sesame as the emphasis mark.

.emphasis-filled-dot

Uses filled dot as the emphasis mark.

.emphasis-open-dot

Uses open dot as the emphasis mark.

.emphasis-filled-triangle

Uses filled triangle as the emphasis mark.

.emphasis-open-triangle

Uses open triangle as the emphasis mark.

.emphasis-filled-circle

Uses filled circle as the emphasis mark.

.emphasis-open-circle

Uses open circle as the emphasis mark.

.emphasis-filled-double-circle

Uses filled double circle as the emphasis mark.

.emphasis-open-double-circle

Uses open double circle as the emphasis mark.

.tate-chu-yoko

Attempts to typeset all consecutive characters within the box horizontally, such that they take up the space of a single character within the vertical line of the box.

.full-width-transform

Forces the writing of a character inside a square.

.full-size-kana-transform

Converts all small Kana characters to the equivalent full-size Kana.

.am

Tentative font-stack for Amharic. There is no guarantee all apps and devices will support it.

.ar

Tentative font-stack for Arabic. There is no guarantee all apps and devices will support it.

.bn

Tentative font-stack for Bengali. There is no guarantee all apps and devices will support it.

.bo

Tentative font-stack for Tibetan. There is no guarantee all apps and devices will support it.

.chr

Tentative font-stack for Cherokee. There is no guarantee all apps and devices will support it.

.fa

Tentative font-stack for Persian. There is no guarantee all apps and devices will support it.

.gu

Tentative font-stack for Gujarati. There is no guarantee all apps and devices will support it.

.he

Tentative font-stack for Hebrew. There is no guarantee all apps and devices will support it.

.hi

Tentative font-stack for Hindi. There is no guarantee all apps and devices will support it.

.hy

Tentative font-stack for Armenian. There is no guarantee all apps and devices will support it.

.iu

Tentative font-stack for Inuktitut. There is no guarantee all apps and devices will support it.

.ja

Tentative default/fallback font-stack for Japanese. There is no guarantee all apps and devices will support it.

.ja-serif-horizontal

Tentative Mincho font-stack for Japanese in horizontal writing mode, with proportional characters. There is no guarantee all apps and devices will support it.

.ja-sans-serif-horizontal

Tentative Gothic font-stack for Japanese in horizontal writing mode, with proportional characters. There is no guarantee all apps and devices will support it.

.ja-serif-vertical

Tentative Mincho font-stack for Japanese in vertical writing mode, with fixed-width characters. There is no guarantee all apps and devices will support it.

.ja-sans-serif-vertical

Tentative Gothic font-stack for Japanese in vertical writing mode, with fixed-width characters. There is no guarantee all apps and devices will support it.

.km

Tentative font-stack for Khmer. There is no guarantee all apps and devices will support it.

.kn

Tentative font-stack for Kannada. There is no guarantee all apps and devices will support it.

.ko

Tentative font-stack for Korean. There is no guarantee all apps and devices will support it.

.lo

Tentative font-stack for Lao. There is no guarantee all apps and devices will support it.

.ml

Tentative font-stack for Malayalam. There is no guarantee all apps and devices will support it.

.or

Tentative font-stack for Oriya. There is no guarantee all apps and devices will support it.

.pa

Tentative font-stack for Punjabi. There is no guarantee all apps and devices will support it.

.si

Tentative font-stack for Sinhalese. There is no guarantee all apps and devices will support it.

.ta

Tentative font-stack for Tamil. There is no guarantee all apps and devices will support it.

.te

Tentative font-stack for Telugu. There is no guarantee all apps and devices will support it.

.th

Tentative font-stack for Thai. There is no guarantee all apps and devices will support it.

.zh

Tentative font-stack for simplified Chinese. There is no guarantee all apps and devices will support it.

.zh-Hant

Tentative font-stack for Chinese in traditional script. There is no guarantee all apps and devices will support it.

.zh-TW

Alias for .zh-Hant.

.zh-HK

Tentative font-stack for Chinese in traditional script (Hong Kong). There is no guarantee all apps and devices will support it.

Generators

.generate-subtle-palette(@baseColor)

Generates a subtle color palette (5 classes) based on the argument.

.generate-comp-palette(@baseColor)

Generates a complementary color palette (5 classes) based on the argument.

.generate-columns(@n)

Generates functional col-[number] classes from the argument.

The argument @n should be a positive integer since it will be used as a divisor for 100%.

Namespaces (packages)

#height-vh

This package outputs functional .h[10→100] classes with a vh value instead of %.

It is “protected” in a CSS feature query (@supports) so that it doesn’t break CSS parsing in some ePub2 Reading Systems.