HTML to PDF Route

HTML to PDF Route

Create professional PDFs using HTML + Playwright + Paged.js.

Step 0: Check & Install Dependencies (Do First)

Run immediately before writing HTML—package download takes time.

/app/.kimi/skills/pdf/scripts/setup.sh

The script only checks status, does not auto-install. If missing, install manually:

• Node.js: brew install node (macOS) / apt install nodejs (Ubuntu)
• Playwright: npm install -g playwright && npx playwright install chromium

Run in background while writing HTML.

Step 1: Write HTML

1. Do NOT load Paged.js: The conversion script injects it automatically; duplicate loading causes page count doubling and layout corruption.
2. Diagrams and Charts:
   • Use Mermaid for flowcharts, sequence diagrams, architecture diagrams (renders as static SVG; must set theme:'neutral')
   • Use <img> tags for data charts (bar, line, pie) — pre-generate with matplotlib
   • Prohibited: ECharts, Chart.js, D3.js, Plotly, or any JS charting library that renders dynamically — causes layout conflicts with Paged.js pagination
   • Chart size rule: Always use landscape figsize (width > height), e.g., figsize=(10, 6). Never use square or portrait. This prevents charts from overflowing the page.

Step 2: Convert to PDF

node /app/.kimi/skills/pdf/scripts/html_to_pdf.js document.html
node /app/.kimi/skills/pdf/scripts/html_to_pdf.js document.html --output output.pdf

After conversion, the script outputs:

• Page count, word statistics, figures/tables count
• Overflow detection: Warns if any pre, table, figure, img, etc. overflows page width
• CSS Counter detection: Warns if CSS counters are used (will break with Paged.js)
• Anomalous pages detection (blank, low-content)

If overflow is detected, add max-width: 100% to the offending element.

Design Principles

LaTeX Academic Style (Default)

Default output should approximate LaTeX academic paper style, not web/UI style.

Prohibited UI Components

LaTeX-Style Patterns

Theorem/Definition boxes (left border, not dark title bar):

.theorem {
    border-left: 3px solid #333;
    padding-left: 1em;
    margin: 1em 0;
}
.theorem-title { font-weight: bold; }
.theorem-content { font-style: italic; }

Algorithm boxes (thin border + white background):

.algorithm {
    border: 1px solid #333;
    padding: 0.5em;
    background: white;
}

Color Standards

Body/Content: #333 text, #f5f5f5 code/table background, grayscale palette. Cover: Depends on document type (see below).

Icons and Emoji

PROHIBITED (unless user explicitly requests): Do NOT use emoji or decorative icons. Emoji fails on Linux (missing fonts), and icons often look unprofessional in formal documents. Use plain text instead.

Cover Design

Style Selection

Default to Minimal for academic contexts, but not mandatory. Choose based on document tone and user preference.

CRITICAL: Cover CSS Requirements

All cover types MUST include these CSS rules to ensure full-bleed cover (no white borders):

/* 1. REQUIRED: Reset browser default margin (prevents 8px white border) */
body {
    margin: 0;
    padding: 0;
}

/* 2. REQUIRED: Remove page margin for cover */
@page :first { margin: 0; }

/* 3. REQUIRED: Cover element setup */
.cover {
    width: 210mm;
    height: 297mm;
    margin: 0;               /* Explicit zero margin */
    position: relative;      /* Required for proper positioning */
    overflow: hidden;        /* Prevent content overflow */
    page-break-after: always;
}

Why all three are needed:

Common mistake: Only setting @page :first { margin: 0; } but forgetting body { margin: 0; } — this causes the "thin white border on left/top, large gap on right/bottom" symptom.

Minimal Cover

<div class="cover">
    <div class="cover-content">
        <h1 class="cover-title">Document Title</h1>
        <p class="cover-subtitle">Subtitle or Document Type</p>
        <div class="cover-meta">
            <p>Author Name</p>
            <p>Institution</p>
            <p>Date</p>
        </div>
    </div>
</div>

.cover { background: white; position: relative; margin: 0; }
.cover-content { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); text-align: center; width: 80%; }
.cover-title { font-size: 28pt; font-weight: 700; color: #333; margin-bottom: 0.5cm; }
.cover-subtitle { font-size: 16pt; color: #666; margin-bottom: 3cm; }
.cover-meta { font-size: 12pt; color: #333; line-height: 2; }

Constraints: No gradients, shadows, rounded cards, or decorative elements.

Designed Cover

Cover background is what separates "acceptable" from "impressive". Plain text cover = mediocre delivery.

Design Principles:

• Background should have center whitespace for title, decorations at edges/corners
• Use low-saturation colors, avoid clashing with content
• Implement with pure CSS (gradients, shapes, pseudo-elements)

Style Reference (choose based on document context, DO NOT copy verbatim—create original designs):

CSS Techniques:

• Geometric shapes: position: absolute + width/height + background or border
• Gradients: radial-gradient(), linear-gradient() with low saturation
• Decorative elements: ::before, ::after pseudo-elements
• Transparency: rgba() or opacity for layering
• Waves: SVG <path> or CSS clip-path

Background Image (if needed)

If using an image instead of CSS, do NOT use CSS background-image — it breaks in Paged.js due to DOM restructuring.

Must use <img> + absolute positioning:

<div class="cover">
    <img class="cover-bg" src="image.jpg" alt="">
    <div class="cover-content">...</div>
</div>

.cover-bg {
    position: absolute; top: 0; left: 0; width: 100%; height: 100%;
    object-fit: cover; object-position: center; z-index: 0;
}
.cover-content {
    position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);
    z-index: 1; text-align: center; width: 80%;
    color: white; text-shadow: 1px 1px 4px rgba(0,0,0,0.6);
}

Why? Paged.js restructures DOM into .pagedjs_page → .pagedjs_sheet → .pagedjs_area → .pagedjs_page_content, breaking CSS backgrounds. <img> with position: absolute ensures full-page coverage.

Typography Standards

• Fonts: Serif preferred (Georgia, "Noto Serif SC")
• Font sizes: Body 11pt, subheadings 14pt, headings 18-20pt
• Line height: 1.5-1.6
• Alignment: If using text-align: justify, must add text-align-last: left to prevent short lines from stretching character spacing

Paged.js Pagination Features

@page Rules

@page {
    size: A4;
    margin: 2.5cm 2cm;
    @top-center { content: string(doctitle); }
    @bottom-center { content: counter(page); }
}
@page :first {
    @top-center { content: none; }
    @bottom-center { content: none; }
}

/* Named pages: hide header/footer on cover and TOC (supports multi-page) */
@page cover { @top-center { content: none; } @bottom-center { content: none; } }
@page toc { @top-center { content: none; } @bottom-center { content: none; } }
.cover { page: cover; }
.toc-page { page: toc; }

/* CRITICAL: Prevent "undefined" in header before h1 appears */
body { string-set: doctitle ""; }
h1 { string-set: doctitle content(); }

Key Properties

page-break-inside: avoid principle: Only use on small atomic components; large containers cause entire blank pages.

/* Correct: Only protect small components */
figure, .theorem, .algorithm { page-break-inside: avoid; }
tr { page-break-inside: avoid; }  /* Single row doesn't break */

/* Wrong: Large containers cause blank pages */
.section, .chapter { page-break-inside: avoid; }

/* Repeat table headers across pages */
thead { display: table-header-group; }

Unexpected blank pages? Common causes: page-break-after: always after cover or consecutive page-break. Solution: Use CSS selectors for pagination (e.g., .abstract:first-of-type { page-break-before: always; }) instead of explicit <div class="page-break">.

Advanced TOC (with Page Numbers)

Use target-counter() for TOC with page numbers and leader dots:

.toc a::after {
    content: leader('.') target-counter(attr(href url), page);
}

TOC items must be <a href="#section-id">, not plain text.

Cross-reference Page Numbers

a.pageref::after {
    content: target-counter(attr(href url), page);
}

Math Formulas (KaTeX)

Include KaTeX CSS and JS, use auto-render extension for automatic rendering of $...$ (inline) and $$...$$ (block).

Colors: Formulas default to black #333, no color highlighting. Equation numbering: Use flex layout + data-* attributes for right-side numbering (CSS counter breaks with Paged.js). Note: Conversion script automatically triggers KaTeX rendering. If source code still shows, check CDN accessibility and don't wrap renderMathInElement in DOMContentLoaded.

Diagrams (Mermaid)

CRITICAL: Height Constraint

Mermaid SVG that exceeds page height will break Paged.js pagination, causing "undefined" errors and blank pages.

Layout Selection (MUST follow):

Complexity Limits:

Configuration

mermaid.initialize({
    startOnLoad: true,
    theme: 'neutral',  // Required!
    themeVariables: {
        primaryColor: '#f5f5f5',
        primaryTextColor: '#333',
        primaryBorderColor: '#999',
        lineColor: '#666'
    }
});

Prohibited

• Themes: default (too blue), forest (high saturation), dark
• Beta features: xychart-beta, etc.
• flowchart TB with >6 nodes or any subgraph

Complex Diagrams: Use Tables Instead

For "technical roadmap", "research framework", "system architecture" with many steps:

DON'T: Single complex Mermaid with 6 subgraphs DO: Table + simplified Mermaid

<!-- Table for details + simple Mermaid for overview -->
<table>
<caption data-label="Table X">Technical Roadmap Phases</caption>
<thead><tr><th>Phase</th><th>Tasks</th><th>Output</th></tr></thead>
<tbody>
<tr><td>Data Collection</td><td>Crawl reviews, gather sales</td><td>Raw database</td></tr>
<tr><td>Data Processing</td><td>Clean, tokenize, label</td><td>Labeled dataset</td></tr>
...
</tbody>
</table>

<div class="mermaid">
flowchart LR
    A[Collection] --> B[Processing] --> C[Training] --> D[Evaluation]
</div>

Debugging

If PDF shows "undefined" or blank pages around diagrams:

1. Diagram too tall → Switch to flowchart LR
2. Too many subgraphs → Reduce to ≤3 or use table
3. Still failing → Replace with table entirely

Professional Components

Use these components appropriately for more complete, professional documents.

Academic Essentials

Layout Enhancements

Auto-numbering Standards

Why Not CSS Counter?

PROHIBITED: Do NOT use counter-reset, counter-increment, or content: counter(...) anywhere in CSS. This includes custom step lists, numbered badges, or any decorative numbering.

Paged.js reorders DOM during pagination, which breaks CSS counters. Common symptoms:

• All numbers show as 0 (e.g., "Figure 0", "Table 0", "Step 0")
• Numbers reset unexpectedly mid-document

Always write numbers explicitly in HTML or use data-* attributes.

Recommended: data-* Attributes

<!-- Figures -->
<figure id="fig-1">
    <img src="chart.png" alt="...">
    <figcaption data-label="Figure 1">System Architecture</figcaption>
</figure>

<!-- Tables -->
<table>
    <caption data-label="Table 1">Performance Comparison</caption>
    ...
</table>

<!-- Equations -->
<div class="equation" data-label="(1)">
    $$E = mc^2$$
</div>

figcaption::before { content: attr(data-label) "  "; font-weight: bold; }
caption::before { content: attr(data-label) "  "; font-weight: bold; }
.equation::after { content: attr(data-label); float: right; }

Anchor placement: id goes on <figure> not <figcaption>, for correct jump positioning.

Prevent Overflow (CRITICAL)

All block elements must not exceed page width. Use this unified rule:

/* Prevent all block elements from overflowing page */
pre, table, figure, img, svg, .mermaid, blockquote, .equation {
    max-width: 100%;
    box-sizing: border-box;
}
pre { overflow-x: auto; white-space: pre-wrap; word-wrap: break-word; }
figure img, figure svg { max-width: 80%; max-height: 40vh; height: auto; }
table { overflow-x: auto; }

/* Prevent justify from stretching short lines */
body { text-align: justify; text-align-last: left; }

/* Prevent long URLs from overflowing */
a { word-break: break-all; }

/* Prevent long formulas from overflowing */
.katex-display { overflow-x: auto; }

/* Prevent long code/words from overflowing */
code { word-break: break-word; }

/* Prevent table rows from breaking mid-cell */
tr { page-break-inside: avoid; }

The conversion script auto-detects overflow and warns. Fix any reported elements.

Vertical Centering (CRITICAL)

PROHIBITED: Do NOT use line-height or vertical-align: middle for centering text in fixed-size containers. These depend on font baseline and are unreliable—text often appears off-center.

Required: Use flexbox. This applies to ALL fixed-size containers with centered content: step numbers, badges, tags, avatar placeholders, icon wrappers, etc.

/* WRONG - text shifts with different fonts */
.step-number {
    width: 1.5em; height: 1.5em;
    line-height: 1.5em;
    text-align: center;
}

/* CORRECT - universal pattern for any centered container */
.step-number {
    width: 1.5em; height: 1.5em;
    display: inline-flex;
    align-items: center;
    justify-content: center;
}

Reference Standards

All citations must be real, no mocking—must verify via search, fabricating any author, title, year, or page number is prohibited.

Strict Correspondence Constraint

In-text <a href="#ref-1">[1]</a> must strictly correspond to end-of-document <li id="ref-1">:

• id must be unique and matching
• No empty links or dangling references

Citation Style (Black Superscript)

a.cite { color: black; text-decoration: none; vertical-align: super; font-size: 0.75em; }

Hanging Indent (Professional Typesetting Mark)

.references li {
    padding-left: 2em;
    text-indent: -2em;
}

Citation Format Selection

Italics Rules (APA)

Book titles, journal names must be italicized, use <i> tag:

<li id="ref-1">Raymond, E. S. (2003). <i>The Art of Unix Programming</i>. Addison-Wesley.</li>
<li id="ref-2">Vaswani, A., et al. (2017). Attention is all you need. <i>NeurIPS</i>, 30, 5998-6008.</li>

Italics scope: Book titles, Journal names (yes), Article titles, Publishers (no)

Footnotes (Paged.js Specific Syntax)

.footnote-ref { float: footnote; }
.footnote-ref::footnote-call { content: counter(footnote); vertical-align: super; font-size: 0.75em; }
.footnote-ref::footnote-marker { content: counter(footnote) ". "; }
@page { @footnote { margin-top: 1em; border-top: 1px solid #ccc; padding-top: 0.5em; } }

Body text<span class="footnote-ref">This is footnote content, automatically typeset at page bottom</span>.

Table of Contents (Must Use Links for Clickability)

<!-- Correct: Use <a> links -->
<ul class="toc">
    <li><a href="#sec1">1. Introduction</a></li>
    <li><a href="#sec2">2. Methods</a></li>
</ul>

<!-- Wrong: Plain text not clickable -->
<div class="toc-item">1. Introduction</div>

/* TOC item: title + leader dots + auto page number */
.toc a::after {
    content: leader('.') target-counter(attr(href url), page);
}

Wrong page numbers? Use target-counter() instead of hardcoded page numbers; Paged.js calculates automatically.

CJK Fonts

Server needs CJK fonts installed or use web fonts:

<link href="https://fonts.googleapis.com/css2?family=Noto+Serif+SC&display=swap" rel="stylesheet">

RTL Languages (Arabic, Persian, Hebrew)

<html dir="rtl" lang="fa">

body { direction: rtl; text-align: right; }
.toc a { display: flex; flex-direction: row-reverse; }

Note: Paged.js has limited support for RTL leader('.'). TOC may need table layout instead.

Script Reference

Tech Stack

Important Notes

Resource Requirements

Chromium memory: ~200-500MB per conversion. For large documents (50+ pages), expect higher usage.

Large Document Strategy

For documents exceeding 50 pages:

1. Split into sections: Write separate HTML files, merge PDFs afterward
2. Reduce complexity: Fewer Mermaid diagrams, simpler tables
3. Increase timeout: Default 120s may not suffice

Offline Operation

The conversion script bundles Paged.js locally (paged.polyfill.js). However:

• KaTeX: Requires CDN or local bundle
• Mermaid: Requires CDN or local bundle
• Web fonts: Require network or local installation

For fully offline operation, include KaTeX/Mermaid JS/CSS in your HTML file directly.

Common Failure Modes