Book PDF Customization¶

Book PDFs are rendered by an external WeasyPrint server that fetches the book’s @@view_weasyprint HTML view. Everything about the PDF layout is therefore controlled by two things: the page templates that produce the HTML and the CSS linked from it. Both can be customized on a running instance without a release:

Templates — site-wide, through a control panel (see PDF Template Overrides)
CSS — per book, through the book’s custom_css field (see Custom CSS)

For the conversion endpoints themselves see the PDF Export section in Book and Library.

Stylesheet Cascade¶

The generated HTML links up to three stylesheets, in this order:

@@book-variables.css — CSS custom properties derived from the book: --book-header-image-url, --book-current-date, --book-current-datetime
++resource++weasyprint_resources/weasyprint_book.css — the packaged default print stylesheet; only linked when the book’s include_default_css field is enabled
@@custom-book.css — the book’s custom_css field

The custom CSS is loaded last, so it can override any rule from the default stylesheet by normal cascade order. @page rules merge, so adding a margin box (e.g. a running header) does not disturb the default page setup.

The custom_css value supports variable substitution:

/* Available variables: $portal_url, $book_url */
.book-header {
    background-image: url($book_url/@@images/header_image);
}

PDF Template Overrides¶

The 7inOne Book PDF Templates control panel (Site Setup → General, or directly at /book-pdf-templates-controlpanel) allows overriding the page templates used for PDF rendering. Editing requires the Manage book PDF templates permission (Manager only by default).

Template	Purpose
`main`	Master macro: HTML skeleton, stylesheet slots
`book`	Whole-book document: title page, TOC section, chapter loop, keyword index
`chapter`	Standalone chapter document (single-chapter PDF)
`chapter_main`	One chapter: heading, blocks, recursion into sub-chapters
`toc`	Table of contents
`keyword_index`	Keyword index (Stichwortverzeichnis) appended after the last chapter
`block_structure`	Block listing within a chapter
`block`	A single block: image, text, table, footnote

How it behaves:

An empty record means the packaged default template is used.
Saved sources are validated: TAL compile errors are rejected on save.
Saving the unchanged default source (or an empty value) resets the record to the default.
Overrides take effect immediately and apply site-wide to all books.

The sources are stored in the registry as wcs.backend.book.pdf_template_<name>.

Warning

An overridden template no longer receives improvements shipped with package upgrades. Reset a template to its default when you no longer need the customization.

Custom CSS¶

Running Headers and Footers¶

The default stylesheet maintains a WeasyPrint running string named heading2 that always holds the current level-1 chapter title (including its TOC number, e.g. “1 Introduction”). By default it is shown in the page footer: the page number sits on the outer edge, the chapter title on the inner edge.

To repeat the chapter title in the header of every page, add to the book’s custom CSS:

@page {
  @top-center {
    content: string(heading2);
  }
}

Pages before the first chapter (title page, table of contents) render an empty header because the string is not set yet.

Page Numbers¶

:right pages are the odd ones (page 1 is a right page), :left pages are the even ones. Page numbers on the outer top edge:

@page :left {
  @top-left {
    content: counter(page);
  }
}

@page :right {
  @top-right {
    content: counter(page);
  }
}

The default stylesheet already prints the page number in the footer. To move it to the header instead of duplicating it, additionally suppress the footer boxes:

@page :left {
  @bottom-left { content: none; }
}

@page :right {
  @bottom-right { content: none; }
}

Named Pages¶

The default stylesheet assigns special page styles that suppress the footer boxes:

Page	Applies to
`clean`	Title page, table of contents, the first page of each level-1 chapter
`:blank`	Blank pages inserted by page breaks
`full`	Full-bleed pages (`margin: 0`, so margin boxes never render)

Custom header boxes are not suppressed automatically. To keep those pages free of headers as well — named-page rules win over :left/:right rules:

@page clean {
  @top-center { content: none; }
  @top-left { content: none; }
  @top-right { content: none; }
}

@page :blank {
  @top-center { content: none; }
  @top-left { content: none; }
  @top-right { content: none; }
}

Standalone Chapter PDFs¶

A PDF can also be generated from a single chapter. The document then contains only that chapter and its sub-chapters, while chapter numbering and heading classes stay book-absolute: converting chapter 1.2 renders its heading as a level-2 heading, numbered “1.2”.

Because the heading2 running string is normally set by level-1 headings only, the standalone view wraps its content in a .standalone-chapter element and the default stylesheet sets the running string from the converted chapter’s own heading — at any nesting level. Custom header and footer rules that reference string(heading2) therefore work unchanged in standalone chapter PDFs.

Keyword Index¶

Keywords marked in paragraph text with the TinyMCE keyword plugin (span.keyword elements) are collected into a keyword index (Stichwortverzeichnis) appended after the last chapter of the whole-book PDF:

The index is disabled by default and must be enabled per book with the Show keyword index in the PDF field on the book’s Book Configuration edit tab.
Entries are sorted alphabetically according to DIN 5007-1 (umlauts sort as their base vowels, ß as ss).
Each entry references the paragraphs containing the keyword, in document order, one page number per paragraph. Page numbers are resolved by WeasyPrint at render time; two paragraphs starting on the same page repeat that page number.
A book without any keywords renders no index section at all.
Standalone chapter PDFs do not contain the index.

The section is produced by the keyword_index template and styled by the default stylesheet (#keyword-index rules), so both can be customized like any other template (see PDF Template Overrides) or via the book’s custom CSS.