render-chinese-math-pdf
Trigger Boundary
Use this skill when the requested deliverable is a readable PDF from Chinese, mixed Chinese/English, or math-heavy Markdown/LaTeX, especially when the likely failure mode is CJK font setup, Unicode math, Pandoc/XeLaTeX behavior, tables, citations, or PDF text readability.
Do not use this skill for general PDF text extraction, image-only OCR, or non-CJK documents unless the user specifically asks for this rendering QA workflow.
Default Architecture
The default renderer is strictly:
Markdown -> Pandoc AST -> LaTeX -> XeLaTeX -> PDF
The repo-owned production entrypoint is:
python scripts/render_scientific_pdf.py input.md output.pdf --root <project-root>
Host-local render_resources/chinese_math_pdf supplies fonts, TeX resources,
and writable cache inputs. It does not own the reusable route-selection,
profile-identity, math-payload, or QA contract.
The resource root is resolved in this order:
- An explicit project-local resource root, when a project command provides one.
CHINESE_MATH_PDF_RESOURCE_DIRS, split on:.- The current namespace override at
CODEX_NAMESPACE_ROOT/.config/ai-skills/local-overrides.toml. - The global/home override at
$HOME/.config/ai-skills/local-overrides.toml; helpers also check the configuredCODEX_GLOBAL_HOMEboundary when present. - Generic ancestor discovery for
render_resources/chinese_math_pdf.
Host-specific resource roots belong only in repo-external local override files or one-off environment variables. Do not hardcode a private absolute path into the reusable skill source, references, or scripts. Once the root is found, run its local scripts from that root.
Font Policy
The default PDF fonts must come from bundle-local font files, not fontconfig or Windows mounts:
- Latin main: TeX Gyre Termes regular, bold, italic, and bold italic from
fonts/texgyre-termes/. - Math: TeX Gyre Termes Math from
fonts/texgyre-termes-math/. - CJK serif: Noto Serif SC regular and bold from
texmf/fonts/opentype/public/noto-cjk/. - CJK sans: Noto Sans SC regular and bold from
texmf/fonts/opentype/public/noto-cjk/.
Do not use Times New Roman, Windows font mounts, fontconfig Times lookup, DejaVu, Liberation, or Fandol as default font sources. Fandol may remain in the bundle only as a legacy or emergency manual fallback.
Workflow
- Locate the source document and the active resource root before compiling.
- Probe the environment:
python scripts/probe_pdf_render_env.py --root <project-root> --prettywhen the script is available, pluspandoc --version,xelatex --version, andkpsewhichchecks when needed. - Compile Markdown through the canonical repo-owned orchestrator:
python scripts/render_scientific_pdf.py input.md output.pdf --root <project-root> --receipt output.receipt.json
- Preserve render authority in this order: explicit user / venue / project render contract; source-specific explicit render settings; canonical formal-note default.
- For
.texsources, use direct XeLaTeX by default with the sameTEXMFHOME,TEXMFVAR,TEXMFCONFIG,TEXMFCACHE,TEXINPUTS, andOSFONTDIRstrategy used byrender_scientific_pdf.py. Do not round-trip native TeX through Pandoc just to share the Markdown wrapper. - If XeLaTeX or a required package/font is missing, report
blocked_missing_dependencywith the exact missing dependency. Do not silently switch to Chromium. - If Pandoc + XeLaTeX fails, inspect the generated header/source or
.logand report the real LaTeX failure. Do not present a Chromium PDF as a successful LaTeX build. - Validate the produced PDF, not only the command exit code:
pdfinfofor page count when available.pdffontsfor embedded/subset TeX Gyre Termes, TeX Gyre Termes Math, Noto Serif SC, and Noto Sans SC usage.pdftotext -layoutfor extractable Chinese, English, formulas, and table row survival.pdftoppmorscripts/validate_pdf_layout.pyfor PNG previews, using all pages or the equation/table-heavy pages when layout risk exists.- the receipt's ordered
Math(mathtype, text)signature and generated-TeX math anchor checks for math-heavy Markdown.
- Treat the task as incomplete if Chinese glyphs, formulas, table layout, or text extraction fail.
Final PDF Delivery
Rendering and delivery are separate completion conditions. A renderer receipt
with status=complete proves only that the PDF was produced and passed the
recorded render checks. It does not prove that the user received the file.
After render QA succeeds:
- Resolve the final PDF to an absolute path and verify that it is the same QA-passed output recorded by the render receipt or command. Confirm that it is a readable, non-empty regular file. Record its size and, when needed to disambiguate candidates, its SHA-256 digest.
- In the first completion response, lead with the current host's native file
entry for that exact PDF. In Codex clients that support local file links, use
a descriptive Markdown link whose target is the verified absolute PDF path,
for example
[final-report.pdf](/absolute/path/final-report.pdf). The user must not have to ask a second time for the PDF. - Keep paths, receipts, hashes, render logs, and preview images as supporting evidence. None of them substitutes for the final PDF file entry.
- Do not invent a
sandbox:URL, upload the PDF to a public or third-party service, or move private material across a new boundary to manufacture a download link.
If the verified PDF is missing or unreadable, or the current host cannot expose it through a legal file entry, do not claim delivery. State that PDF rendering may have succeeded but user file delivery is incomplete, name the failed check, and give the smallest truthful recovery step. A server path alone is diagnostic information and must not be presented as a delivered file.
Route and Profile Identity
For every render, record the effective route/profile identity. At minimum this means authority source, route, engine, paper size, margins, line spacing, TOC/numbering policy, font policy, resource root, and source path. Same-request retry stability applies to the same resolved profile. If the user explicitly changes paper size, venue template, class, or another format-defining requirement, record a new effective profile identity instead of calling it a stability regression.
The canonical formal-note profile is version-controlled at
profiles/canonical_formal_note.json. It is the default only when no stronger
user, venue, project, or source contract applies. Project/venue templates may
use their own fonts, class, margins, numbering, paper size, headers, and
footers; apply glyph/math/layout QA relevant to that route, not the canonical
font allowlist.
Chromium Diagnostic Boundary
scripts/render_markdown_pdf_chromium.py is an explicit diagnostic tool. Use it
only when the user asks for browser/HTML/CSS rendering or when running an
isolated diagnostic experiment. It is never an automatic fallback for a failed
Pandoc + XeLaTeX render.
Completion States
- Renderer
complete: PDF rendered through Pandoc + XeLaTeX and passed command, page-count, font, text-extraction, and complete-document visual checks using all pages or all declared high-risk pages for the request. This preserves the existing receipt meaning and is not user-delivery completion. partial_complete: PDF rendered, but non-critical warnings or limited QA remain and are reported with next steps.blocked_missing_dependency: no safe Pandoc + XeLaTeX route exists; report the missing command/package/font and attempted route.qa_failed: a PDF was produced but readability, glyphs, pagination, or text extraction failed.
For a user request whose deliverable is the PDF file, claim overall completion
only when renderer complete and first-response delivery of the same verified
PDF both succeed. Otherwise report the renderer state and delivery state
separately.
References
- Read
references/portable-rendering.mdwhen setting up a new repo, replacing a host-local override path, or handling missing TeX/font dependencies. - Read
references/citation-cleanup.mdwhen source text contains AI citation handles, private-use marker characters, broken bibliography tokens, or generated reference placeholders. - Read
references/checklists.mdbefore final PDF QA. - Read
references/source-notes.mdonly when you need provenance for why this skill avoids host-specific assumptions.