---
name: template-css-knowledge
description: Everything about how the full HTML document is assembled (src/template.ts) and the theme CSS layering order. Covers buildHtml, the readCss cache, KaTeX font-path rewrite, fonts.css/tokens.css/base.css/theme-*.css/highlight-*.css/print.css layering, :root and [data-mode="dark"] blocks, @page margin boxes for running chrome, cover/toc sections, page-break, full-bleed contract, and the interplay with design overrides and the accent shortcut. Use when editing the HTML shell, CSS themes, page chrome, or debugging a layering / specificity issue.
triggers: buildHtml, template.ts, themes.css, tokens.css, base.css, print.css, highlight-light.css, highlight-dark.css, @page, page chrome, running header, running footer, page numbers, full-bleed, KaTeX CSS, page break, cover page, toc, data-mode, CSS variable, --brand, --bg-page, readCss cache, paletteToCss, buildDesignOverride, buildPageChromeCss, escapeCssString
---
# Template & CSS
All HTML generation for the rendered PDF lives in [src/template.ts](src/template.ts). Every page's appearance is a deterministic function of `buildHtml(BuildHtmlOptions)` + the loaded theme CSS in [src/themes/](src/themes).
## Entry point: `buildHtml(opts)`
```ts
export function buildHtml(opts: BuildHtmlOptions): string
```
Returns a complete HTML document (starting with ``) that Chromium loads via `page.goto(file://...)` in [src/pdf.ts](src/pdf.ts).
Options surface:
```ts
interface BuildHtmlOptions {
bodyHtml: string; // rendered markdown body
title?: string; // + cover
mode?: 'light' | 'dark';
cover?: boolean;
toc?: boolean;
tocHtml?: string; // pre-rendered by the second-pass TOC extract
subtitle?: string;
fileList?: string[]; // merge-mode cover list
showLinkUrls?: boolean; // body class toggles inline URL printing
accent?: string | null;
design?: DesignTokens | null;
pageNumbers?: boolean;
headerText?: string; // tokens: {file} {title} {date}
footerText?: string;
}
```
## Document shape
```html
<!DOCTYPE html>
<html lang="en" data-mode="{mode}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{escaped title}
{coverHtml?}
{tocSection?}
{bodyHtml}
{mermaidScript}