Kagen

kagen · 紙源

紙源 · かげん - paper source. PDF generation companion to Kami.

Kami designs, Kagen ships. Converts Kami HTML templates to production-grade PDF using Chromium (Playwright), bypassing WeasyPrint's Windows limitations.

Why Kagen

Based on benchmarks (pdf4.dev 2026), engineering discussions (HN, Stack Overflow, BrowserStack), and production experience from DocRaptor, customjs.space, and print-css.rocks.

Prerequisites

• Node.js 20+
• Playwright (npx playwright auto-installs on first use)
• Chromium browser installed (npx playwright install chromium)
• Kami HTML templates (any valid HTML with print CSS)

Quick start

npx playwright pdf "file:///path/to/doc.html" "output.pdf"

Or from Node.js:

const { chromium } = require('playwright');
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('file:///path/to/doc.html', { waitUntil: 'networkidle' });
await page.pdf({
  path: 'output.pdf',
  format: 'A4',
  printBackground: true,
  margin: { top: '0', bottom: '0', left: '0', right: '0' }
});
await browser.close();

Production settings (from professional research)

Page options

await page.pdf({
  path: 'output.pdf',
  format: 'A4',              // or 'Letter', 'A3'
  printBackground: true,     // always true — renders parchment bg
  margin: { top: '0', bottom: '0', left: '0', right: '0' },
  // For screen media (not print):
  // await page.emulateMedia({ media: 'screen' });
});

Critical CSS rules for reliable PDF output

/* Always include in your HTML template header */

@page {
  size: A4;
  margin: 24mm 26mm 26mm 26mm;
  background: #f5f4ed;
  widows: 4;
  orphans: 4;
}

/* Force background colors in Chromium */
* {
  -webkit-print-color-adjust: exact;
  print-color-adjust: exact;
}

/* Avoid orphan text lines — high widows/orphans prevents single-line splits */
body { widows: 4; orphans: 4; }
p    { widows: 3; orphans: 3; }
li   { widows: 2; orphans: 2; }

/* Page break control — only on chapters with heavy content */
.chapter { }
.chapter.break { break-before: page; }

/* Never let a heading sit alone at page bottom */
h1, h2, h3, h4 { break-after: avoid; }

/* Keep these blocks intact — never split across pages */
table, pre, figure, .callout, .card,
blockquote, .finding-header, .takeaway {
  break-inside: avoid;
}

/* Avoid code blocks getting orphaned from their preceding paragraph */
pre {
  margin-top: 6pt;
  page-break-before: avoid;
}

/* Tables should not break rows across pages */
table tr {
  break-inside: avoid;
}

Visual patterns by document type

Each document type needs its own set of visual patterns. Apply accordingly:

Rule: if the document type isn't in the table, choose the closest one and adapt.

Near-empty pages prevention

Nothing looks more amateur than a page with 2 lines. Causes and solutions:

AI anti-patterns in documents

Validate that content inherited from Kami doesn't have these marks:

Best practices from professionals

Warm mode (production pipeline)

const { chromium } = require('playwright');

class PDFRenderer {
  constructor() {
    this.browser = null;
  }

  async start() {
    this.browser = await chromium.launch();
  }

  async render(htmlPath, outputPath) {
    const page = await this.browser.newPage();
    await page.goto('file:///' + htmlPath.replace(/\\/g, '/'), {
      waitUntil: 'networkidle'
    });
    await page.pdf({
      path: outputPath,
      format: 'A4',
      printBackground: true,
      margin: { top: '0', bottom: '0', left: '0', right: '0' }
    });
    await page.close();
  }

  async stop() {
    await this.browser.close();
  }
}

Font embedding

Chromium embeds system fonts by default. For custom fonts (like TsangerJinKai02 in Kami):

@font-face {
  font-family: "CustomFont";
  src: url("fonts/CustomFont.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
}

Place font files relative to the HTML and use relative src paths. Chromium resolves them from the HTML file's directory.

Troubleshooting

CSS visual pattern snippets

Concrete patterns to include in the HTML by document type:

/* Severity badges (pentest, security) */
.badge-high { background: #f5e8e8; color: #a83030; display: inline-block; padding: 2pt 7pt; border-radius: 3pt; font-size: 8pt; font-weight: 500; text-transform: uppercase; }
.badge-medium { background: #f5ede2; color: #b86a25; display: inline-block; padding: 2pt 7pt; border-radius: 3pt; font-size: 8pt; font-weight: 500; text-transform: uppercase; }
.badge-ok { background: #e8f2ec; color: #2a7a4a; display: inline-block; padding: 2pt 7pt; border-radius: 3pt; font-size: 8pt; font-weight: 500; text-transform: uppercase; }

/* Risk bar (pentest exec summary) */
.risk-bar { display: flex; gap: 2pt; margin: 8pt 0 14pt 0; height: 12pt; }
.risk-bar .seg { border-radius: 2pt; display: flex; align-items: center; justify-content: center; font-size: 7pt; color: #fff; font-weight: 500; }

/* Code blocks with left border (pentest, technical) */
pre { border-left: 2.5pt solid #1B365D; border-radius: 3pt; background: #faf9f5; padding: 10pt 14pt; font-family: Consolas, monospace; font-size: 9pt; line-height: 1.5; break-inside: avoid; }

/* Impact/Remediation boxes (pentest) */
.impact-box, .remediation-box { border-left: 2pt solid #e8e6dc; padding-left: 12pt; margin: 10pt 0 14pt 0; break-inside: avoid; }
.impact-box .label, .remediation-box .label { font-size: 8.5pt; letter-spacing: 0.8pt; text-transform: uppercase; font-weight: 500; color: #1B365D; margin-bottom: 4pt; }

/* Cover accent line */
.cover-line { width: 60pt; height: 2pt; background: #1B365D; margin: 20pt 0; border-radius: 1pt; }

/* Pipeline flow (4 step horizontal) */
.pipeline-flow { display: flex; gap: 0; margin: 18pt 0; break-inside: avoid; }
.pipeline-step { flex: 1; text-align: center; padding: 10pt 8pt; }
.pipeline-step .dot { width: 6pt; height: 6pt; border-radius: 50%; background: #1B365D; margin: 0 auto 5pt auto; }
.pipeline-step + .pipeline-step { border-left: 0.5pt dotted #e8e6dc; }
.pipeline-step .name { font-size: 9pt; font-weight: 500; color: #141413; margin-bottom: 3pt; }
.pipeline-step .desc { font-size: 7.5pt; color: #6b6a64; line-height: 1.35; }

/* Keep-together wrapper */
.keep-together { break-inside: avoid; }

Self-review protocol (mandatory)

Don't generate the PDF without passing this checklist. Each item is a real failure documented in previous iterations.

Structural (blocking)

• Each chapter has enough content to fill >1/3 of a page
• No sections with just heading + 1 short paragraph (merge)
• No near-empty pages (2 lines alone)
• break-before: page only on chapters with dense content

Visual (high priority)

• Visual elements match the document type (badges, risk bars, code blocks, etc.)
• Tables have proper styling (optional zebra, padding, clear headers)
• Code blocks are distinguishable from body (border, background, monospace)
• No repeated em dashes — used as label/value separators
• There's variety in visual rhythm (not all pages the same)

Content (high priority)

• Every categorical claim has its visible source ("according to X...")
• Internal methodology is distinguished from verified fact (disclaimer if applicable)
• No redundant content between chapters (sources, repeated lists)
• Every paragraph is necessary (if it can be removed without loss, remove it)

Technical (blocking)

• printBackground: true in Playwright configuration
• -webkit-print-color-adjust: exact in CSS
• widows: 4; orphans: 4 in @page and body
• break-inside: avoid on pre, table, blockquote, callout
• table tr { break-inside: avoid } so tables don't split rows

Complete HTML example

Minimum functional template that includes all essential patterns. Copy and adapt:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Document Title</title>
<style>
  @page { size: A4; margin: 24mm 26mm 26mm 26mm; background: #f5f4ed; widows: 4; orphans: 4; }
  * { box-sizing: border-box; margin: 0; padding: 0; -webkit-print-color-adjust: exact; }
  :root {
    --parchment: #f5f4ed; --ivory: #faf9f5; --near-black: #141413;
    --dark-warm: #3d3d3a; --olive: #504e49; --stone: #6b6a64;
    --brand: #1B365D; --border: #e8e6dc; --border-soft: #e5e3d8;
    --serif: Charter, Georgia, Palatino, "Times New Roman", serif;
    --mono: Consolas, "Courier New", monospace;
  }
  body { font-family: var(--serif); font-size: 10.5pt; line-height: 1.65; color: var(--near-black); background: var(--parchment); widows: 4; orphans: 4; }
  h1 { font-size: 24pt; border-left: 2.5pt solid var(--brand); padding-left: 8pt; margin: 0 0 10pt 0; break-after: avoid; }
  h2 { font-size: 16pt; margin: 24pt 0 8pt 0; break-after: avoid; }
  p { margin: 0 0 10pt 0; widows: 3; orphans: 3; }
  table { width: 100%; border-collapse: collapse; font-size: 9.5pt; margin: 12pt 0; break-inside: avoid; }
  table th { text-align: left; padding: 6pt 8pt; border-bottom: 1pt solid var(--border); background: var(--ivory); }
  table td { padding: 5pt 8pt; border-bottom: 0.3pt solid var(--border-soft); }
  table tr { break-inside: avoid; }
  pre { border-left: 2.5pt solid var(--brand); border-radius: 3pt; background: var(--ivory); padding: 10pt 14pt; font-size: 9pt; font-family: var(--mono); break-inside: avoid; margin: 6pt 0 10pt 0; }
  .callout { background: var(--ivory); border-left: 2pt solid var(--brand); padding: 10pt 14pt; border-radius: 3pt; margin: 12pt 0; break-inside: avoid; }
  .keep-together { break-inside: avoid; }
  .break { break-before: page; }
  /* Add visual patterns by document type (badges, risk bar, etc.) */
</style>
</head>
<body>
<!-- Cover -->
<section style="min-height:240mm;display:flex;flex-direction:column;justify-content:space-between;padding:40mm 0 0 0;break-after:page;">
  <div>
    <div style="font-size:10pt;color:var(--brand);letter-spacing:2pt;text-transform:uppercase;margin-bottom:18pt;">Document Type</div>
    <div style="font-size:40pt;font-weight:500;line-height:1.12;margin-bottom:16pt;">Main Title</div>
    <div style="width:60pt;height:2pt;background:var(--brand);margin:20pt 0;border-radius:1pt;"></div>
    <div style="font-size:14pt;color:var(--olive);max-width:85%;">Subtitle or description</div>
  </div>
  <div style="font-size:10pt;color:var(--stone);">Author · Date</div>
</section>
<!-- Chapter -->
<section class="break">
  <h1>Chapter Title</h1>
  <p>Document content. Verify sources (research), humanize text (humanize), design with Kami.</p>
  <!-- Tables, lists, callouts as needed -->
</section>
</body>
</html>

Integration with Kami

# One-liner from Kami HTML to PDF
npx playwright pdf "file:///path/to/kami-output.html" "final.pdf"

Sources

• Playwright PDF API docs
• pdf4.dev HTML-to-PDF benchmark 2026
• BrowserStack: Generate PDFs with Playwright
• print-css.rocks: CSS Paged Media tutorial
• DocuPotion: Generate PDFs with Playwright
• CSS Paged Media W3C specification
• Blog.rasc.ch: Generating PDFs with Playwright and Go
• HN: What is the open-source way to convert HTML to PDF

Workflow

Step 1: Validate HTML template

Before rendering, verify the template is production-ready:

1. Open the HTML in a browser first: confirm fonts load, CSS applies, layout renders correctly at print size
2. Check that @page rules specify explicit size (A4, Letter) and margins
3. Verify -webkit-print-color-adjust: exact and print-color-adjust: exact are set on *
4. Confirm all @font-face declarations use relative paths, not absolute filesystem paths

Step 2: Configure render settings

1. Set format (A4, Letter, A3) to match the template's @page { size: } declaration
2. Set printBackground: true — always. Never skip this. Chromium strips backgrounds by default
3. Set Playwright margin: { top: '0', bottom: '0', left: '0', right: '0' } — use CSS @page margins instead
4. Use waitUntil: 'networkidle' to ensure fonts, CSS, and images are fully loaded before rendering

Step 3: Render PDF

1. Launch browser once (warm mode) — reuse for all documents in batch
2. Navigate with file:// protocol to avoid CORS and authentication issues with local files
3. Await page.pdf() with configured options
4. Close page after each render but keep browser alive for next document

Step 4: Validate output PDF

1. Open PDF and check: parchment/tinted background rendered (not white), fonts embedded correctly, page breaks occur at logical points
2. Scan every page for near-empty pages (2 lines or less floating at page top)
3. Verify code blocks, callouts, and tables are not split across page boundaries
4. Check CJK characters render correctly if document contains Chinese, Japanese, or Korean text

Step 5: Apply visual patterns by document type

1. Pentest/security report: severity badges, risk bars, finding headers, styled code blocks, impact/remediation boxes
2. One-pager/executive summary: glance grid (4 metrics), lead paragraph, takeaway box, cover with decorative accent line
3. White paper/long document: chapter breaks on dense sections, callouts, keep-together wrappers on critical blocks
4. Letter: wide margins (25mm), formal greeting/closing, single-column, no unnecessary breaks
5. Resume: dense body (9.2pt), metric row, project bullets with action + result format

Step 6: Run self-review protocol

Complete ALL four checklist categories before final output: Structural (blocking), Visual (high priority), Content (high priority), Technical (blocking). Every item in the self-review protocol is a real failure mode documented from previous iterations.

Error Handling

Anti-Patterns

Checklist

• Skill loads without errors in the AI agent
• YAML frontmatter is valid (description, compatibility, audience)
• Workflow section provides clear step-by-step instructions
• Error handling section covers common failure modes
• All referenced files (references/, scripts/, assets/) exist
• Skill triggers correctly for intended use cases
• No broken links or missing resources