HTML优先的PDF生成技能

name: minimax-pdf
description: HTML-first PDF production skill for reports, papers, and structured documents. Must be applied before generating PDF deliverables from HTML.

A. Scope and Operating Contract

This skill governs authoring and converting HTML into print-quality PDF.

Primary output goals:

• Stable pagination and predictable layout on Linux runtime.
• Searchable/selectable text (no screenshot-based fallback).
• Professional, citation-safe long-form documents.

B. Hard Constraints (Do Not Violate)

B1. Conversion entrypoint

For HTML->PDF, use html_to_pdf only.

Forbidden:

• Screenshot/print hacks or manual browser printing
• Direct invocation of low-level local scripts for conversion

Reason: image-stitch paths degrade text quality and create pagination discontinuity.

B2. Rendering safety rules

• Do not inject Paged.js manually. The runtime pipeline handles loading.
• Do not rely on CSS counters (counter-reset, counter-increment, counter()).
• Do not use runtime charting engines (ECharts, Chart.js, D3, Plotly, etc.).
• Charts should be pre-rendered as static images and prefer landscape aspect ratio.
• Decorative emoji/icon glyphs are disallowed unless explicitly requested.

C Intent Parsing

Classify the task before execution:

| Intent | Typical user request | Pipeline |
|---|---|---|
| Build | "写一份报告并导出 PDF" | build-pdf |
| Transform | "把这篇内容翻译后做成 PDF" | transform-pdf |
| Existing PDF ops | "提取/合并/拆分 PDF" | process-existing-pdf |
| LaTeX explicit | "请用 LaTeX/.tex/Tectonic" | latex-compile |

Clarification policy:

• If request is clear, execute directly.
• If ambiguous, ask once with a compact checklist:
• 文档类型/主题
• 是否要封面
• 字数或页数边界
• 语言与格式偏好

Important clarification behavior:

• Ask at most one clarification round for intent.
• After that, execute with explicit assumptions rather than repeatedly asking.

D. Content Governance

D1. Language policy

• Chinese user query -> Chinese content
• English user query -> English content
• User-specified language -> obey exactly

D2. Outline policy

• User provides outline -> preserve hierarchy/order, no silent restructuring
• No outline -> choose structure by document type and keep narrative flow consistent

D3. Citation integrity

• Never invent references.
• Every citation must be verifiable (author/title/year/source).
• Reused source should keep the same citation index.

Recommended citation style for this skill: IEEE numeric.

Sample reference list:

[1] R. Patel and L. Chen, "A comparative study on model routing," Journal of Applied AI, vol. 8, no. 3, pp. 44-58, 2025.
[2] M. Rivera, Systems Design Handbook, 2nd ed. New York, NY, USA: Northbridge Press, 2024.
[3] T. Huang, "Model evaluation checklist," Research Notes, https://example.org/eval (accessed Feb. 14, 2026).

E. Conversion Fidelity Checklist

When transforming existing material (translation/rewrite/reformat), preserve source fidelity:

E1. Links

• Keep original destination URL in href.
• Do not replace links with plain text.
• Ensure conversion uses preserve_links=true.

E2. Images

Use a three-pass check:

1. Count extracted image assets
2. Count <img> tags in HTML
3. Validate post-conversion image statistics

E3. Structure

• Preserve source section sequence and anchor semantics.
• Keep figure/table placement and numbering intent.
• Do not add synthetic cover if source had none.

F. Implementation Blueprint

F1. Forbidden patterns

| Pattern | Why unstable | Replacement |
|---|---|---|
| CSS content counters for numbering | pagination DOM shifts can break numbering | explicit labels in markup |
| Dynamic JS chart libraries at render-time | print pagination conflicts | pre-rendered static charts |
| Emoji/icon-heavy typography | Linux fallback inconsistency | plain text labels |

Chart image policy:

• Prefer landscape charts (width > height) to reduce page-break artifacts.

F2. Overflow guards (required baseline)

/* Keep printable blocks inside page width */
pre, table, figure, img, svg, .diagram, blockquote, .eq-block {
  max-inline-size: 100%;
  box-sizing: border-box;
}

pre {
  overflow-x: auto;
  white-space: pre-wrap;
  overflow-wrap: anywhere;
}

figure img, figure svg {
  max-inline-size: 82%;
  max-block-size: 42vh;
  height: auto;
}

table { overflow-x: auto; }
.katex-display { overflow-x: auto; }
code { overflow-wrap: anywhere; }
a { overflow-wrap: anywhere; }
tr { break-inside: avoid; }

body {
  text-align: justify;
  text-align-last: start;
}

F3. Page model setup

@page {
  size: A4;
  margin: 2.4cm 1.9cm;
  @top-center { content: string(doc_title); }
  @bottom-center { content: counter(page); }
}

@page :first {
  @top-center { content: none; }
  @bottom-center { content: none; }
}

@page titlepage {
  @top-center { content: none; }
  @bottom-center { content: none; }
}

@page contents {
  @top-center { content: none; }
  @bottom-center { content: none; }
}

body { string-set: doc_title ""; }
h1 { string-set: doc_title content(); }
.cover-page { page: titlepage; }
.toc-sheet { page: contents; }

Pagination notes:

• Apply break-inside: avoid only to compact units (single figure, single row, callout box).
• Never apply it to large wrappers (chapter/section container).
• Use thead { display: table-header-group; } for multi-page table headers.

F4. Visual direction

Default target is print-academic, not dashboard aesthetics.

Avoid:

• heavy card shells
• KPI tile walls
• dark decorative title bars
• oversized rounded/shadowed ornaments

Prefer:

• plain headings + thin dividers
• data-dense tables
• restrained grayscale palette
• simple, high-contrast typography

Type scale suggestion:

• Body: 11pt
• Subheading: 14pt
• Primary heading: 18-20pt
• Line height: 1.6-1.7

F. Cover page rules

Full-bleed baseline:

*,
*::before,
*::after { box-sizing: border-box; }

html, body {
  margin: 0;
  padding: 0;
}

@page :first {
  margin: 0;
}

.cover-page {
  inline-size: 210mm;
  block-size: 297mm;
  position: relative;
  display: grid;
  place-items: center;
  overflow: hidden;
  break-after: page;
}

Cover variants:

• Minimal: white background, centered title/meta, no decoration
• Designed: low-saturation geometry/gradient, keep center area clear for title

If using image background, do not use CSS background-image. Use absolute <img>:

<section class="cover-page">
  <img class="cover-photo" src="cover.jpg" alt="">
  <div class="cover-layer">...</div>
</section>

.cover-photo {
  position: absolute;
  inset: 0;
  inline-size: 100%;
  block-size: 100%;
  object-fit: cover;
  object-position: center;
  z-index: 0;
}

.cover-layer {
  position: absolute;
  inset-block-start: 50%;
  inset-inline-start: 50%;
  transform: translate(-50%, -50%);
  z-index: 1;
}

F5. Numbering, references, TOC

Use explicit labels in markup, not CSS counters.

<figure id="arch-overview">
  <img src="system-overview.png" alt="System overview">
  <figcaption data-caption="Figure 1">Architecture Overview</figcaption>
</figure>

<table id="latency-table">
  <caption data-caption="Table 1">Latency by Scenario</caption>
  ...
</table>

<div class="eq-block" data-eq="(1)">$$f(x)=x^2+1$$</div>

figcaption::before {
  content: attr(data-caption) " ";
  font-weight: 700;
}

caption::before {
  content: attr(data-caption) " ";
  font-weight: 700;
}

.eq-block::after {
  content: attr(data-eq);
  float: right;
}

Anchor placement rule:

• Put id on the highest logical container (figure, table, section wrapper), not on inline caption text.

TOC example with computed page numbers:

<nav class="toc-sheet" aria-label="Contents">
  <ul class="toc-list">
    <li><a href="#sec-intro">1 Intro</a></li>
    <li><a href="#sec-method">2 Method</a></li>
  </ul>
</nav>

.toc-list {
  list-style: none;
  margin: 0;
  padding: 0;
}

.toc-list li { margin: 0.45em 0; }

.toc-list a {
  display: flex;
  gap: 0.5em;
  color: inherit;
  text-decoration: none;
}

.toc-list a::after {
  margin-inline-start: auto;
  content: target-counter(attr(href url), page);
}

Optional in-text page reference:

a.page-ref::after {
  content: " (p." target-counter(attr(href url), page) ")";
  opacity: 0.72;
  font-size: 0.86em;
}

F6. Formula and diagram policy

• For math, use KaTeX with auto-render.
• Keep formula color neutral and print-safe.
• For Mermaid, keep topology simple; if rendering becomes unstable, replace with static image.

F7. Reusable layout patterns

Definition block:

.definition {
  border-inline-start: 3px solid #475569;
  padding-inline-start: 1rem;
  margin: 1rem 0;
}

.definition-title { font-weight: 700; }
.definition-body { font-style: italic; }

Procedure block:

.procedure {
  border: 1px solid #cbd5e1;
  padding: 0.75rem;
  background: #f8fafc;
}

Fixed-size centered badges must use flexbox:

.badge-index {
  inline-size: 1.7em;
  block-size: 1.7em;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  border: 1px solid #cbd5e1;
  border-radius: 999px;
}

F8. Citation anchors and footnotes

Reference anchor consistency:

• Every <a href="#ref-n">[n]</a> must map to one <li id="ref-n">.
• No dangling reference IDs.

a.citation {
  color: #1f2937;
  text-decoration: none;
  vertical-align: super;
  font-size: 0.78em;
}

.ref-list li {
  padding-inline-start: 2em;
  text-indent: -2em;
}

Paged footnote pattern:

.fn {
  float: footnote;
}

.fn::footnote-call {
  content: counter(footnote);
  vertical-align: super;
  font-size: 0.78em;
}

.fn::footnote-marker {
  content: counter(footnote) ". ";
}

@page {
  @footnote {
    margin-top: 1.1em;
    border-top: 1px solid #d1d5db;
    padding-top: 0.55em;
  }
}

F9. Layout tuning guide

When page count or layout does not meet targets, adjust in this priority order:

| Symptom | First move | Second move | Avoid |
|---|---|---|---|
| Page count exceeds target | reduce heading sizes | reduce line-height slightly | aggressive body font shrink |
| Page count below target | increase line-height | increase page margins slightly | adding low-value filler text |
| Table overflows page width | reduce cell padding | allow word wrapping on long tokens | forcing fixed table widths |
| Figure breaks layout | reduce figure max-width/max-height | move figure near paragraph boundary | avoid on large parent containers |
| Text looks cramped | raise line-height | increase side margins slightly | oversized heading jumps |
| Resume too sparse/dense | tune margins first | then adjust heading scale | changing section order silently |

G Fidelity Gates

Run all gates before final delivery.

G1. Hyperlinks

• Ensure external links keep original href.
• In conversion call, enforce preserve_links=true.

G2. Images (3-pass)

1. Source extraction count (baseline)
2. HTML <img> count and mapping
3. Post-conversion result check

G3. Anchor integrity

• Cross-references must point to real IDs.
• Place id on top-level containers (figure, section wrapper), not inner text nodes.
• For TOC and page refs, use print-aware links with page target resolution (target-counter).

G4. Structure parity (for transforms)

• Keep source section order unless user requests restructuring.
• Do not inject a cover page when source had none (unless user requests one).