# 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](#pdf-template-overrides))
- **CSS** — per book, through the book's `custom_css` field (see
  [Custom CSS](#custom-css))

For the conversion endpoints themselves see the PDF Export section in
[Book and Library](book.md).


## Stylesheet Cascade

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

1. `@@book-variables.css` — CSS custom properties derived from the book:
   `--book-header-image-url`, `--book-current-date`, `--book-current-datetime`
2. `++resource++weasyprint_resources/weasyprint_book.css` — the packaged
   default print stylesheet; only linked when the book's `include_default_css`
   field is enabled
3. `@@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:

```css
/* 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:

```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:

```css
@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:

```css
@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:

```css
@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](#pdf-template-overrides)) or
via the book's custom CSS.