Blitz’ documentation

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.

.oldstyle

Defines an oldstyle font-stack based on Minion Pro 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

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

.underline

Applies an underline 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 which 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, which values are counted in tens.

.h-[10→100]

Applies an height (%) to the element.

You must pick the height, which 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, which 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 on Medium.

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.

@body-font-size

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

Default is 16.

@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.

@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.

@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.

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.

#responsive-table

An experimental package leveraging a data-th attribute to make tables responsive.

Since media queries are untrustworthy in Reading Systems at the moment, you should probably not use this package.