Theming guide

Each book gets one stylesheet, assembled in this order:

  1. @font-face rules for style.fonts
  2. themes/base.css - structure shared by every theme (scene breaks, epigraphs, footnotes, figures, title/copyright/dedication/TOC pages)
  3. themes/<theme>.css - typography: fonts, paragraph style, headings
  4. A Pygments stylesheet for pre.highlight (style.code_style)
  5. Your style.css file, if set

The same CSS is used in the EPUB (css/style.css) and inside the print HTML, which adds a paged-media layer on top.

The three built-in themes

theme look paragraphs headings
classic Georgia/Times serif, 1.45 line height indented, justified, no gap centered, light, generous space
modern Helvetica/Arial sans, 1.55 line height flush left, spaced bold, left, orange rule under chapter title
manuscript Courier, 1.9 line height indented, ragged right uppercase centered chapter titles

E-readers let readers override fonts and sizes, so themes use relative units and font stacks rather than fixed pixel sizes.

Hooks you can style

The XHTML is deliberately plain and classed so a few lines of CSS go a long way.

selector what it is
body.fl-smallcaps, .fl-dropcap, .fl-none the first_line choice
p.first first paragraph of a chapter, section or scene
p.opening the very first paragraph after the chapter heading (drop cap target)
.scenebreak scene-break ornament (a div, so every reader renders it)
blockquote.epigraph, p.attribution epigraph and its attribution line
figure.figure, figcaption captioned images
sup.noteref, section.footnotes, section.endnotes, a.backlink notes
pre.highlight, code code blocks (token classes are Pygments': .k, .s2, ...)
section.titlepage, .copyright-page, .dedication-page, .part-page, nav.toc generated pages

Example: a drop cap in your accent colour

/* style.css */
.fl-dropcap p.opening::first-letter { color: #8a1c1c; font-size: 3.6em; }
h1 { letter-spacing: 0.12em; text-transform: uppercase; }

[style]
first_line = "dropcap"
css = "style.css"

The print HTML puts everything inside <style>; add print rules to your CSS file freely, e.g. a different page size per document using named pages (section#appendix-harmonics { page: wide; } plus @page wide { size: 8.5in 5.5in; }). Chrome supports named pages and margin boxes; target-counter(), leader() and string-set are honoured by Paged.js and ignored by Chrome (see epub-internals.md for how bookforge pdf compensates).

Writing a new built-in theme

Add src/bookforge/themes/<name>.css, add the name to THEMES in config.py, and keep it to typography: base.css already provides structure.