minimax-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).