PDF Production

PDF Production

A PDF is the only deliverable format whose defects are invisible in the source. Text that fits in Markdown clips in a PDF. A table that renders on screen breaks across a page. A font that displays correctly in the editor drops accented capitals in the output.

Therefore the rule that governs this skill: a generated PDF is not a finished PDF until the rendered pages have been inspected. Not the source. The pages.

Governed by document-core for content and document-design for layout. This skill owns the engine, the pipeline and the verification.

1. Engine selection

There is no correct default. Choose from the document.

Decision procedure:

1. Is the source already HTML, or does it need CSS layout? Chromium or WeasyPrint.
2. Does it need running headers, page counters or precise pagination? WeasyPrint or Typst, not a Markdown converter.
3. Is it mathematics? LaTeX.
4. Is it produced repeatedly and reviewed in version control? Prefer a text source: Typst, LaTeX or HTML, not a binary or a manual process.
5. Is it a fixed official form? A library, filling fields.

Constraints that override preference:

• Verify the engine exists before promising a PDF. Check the command runs. A pipeline that assumes an engine is a pipeline that fails on someone else's machine.
• Prefer what the project already uses. A second engine is a second set of fonts, a second CSS dialect and a second class of bug.
• Prefer an engine installable without a browser or a full distribution when the document is simple. Do not install 300MB to produce a two-page letter.
• Record the engine and its version in the recipe. The same source with a different version does not produce the same pages.

2. Structure

Typography and layout are decided by document-design and applied here. This skill does not re-decide them.

3. Font embedding

The most common silent PDF defect.

• Every font is embedded. A PDF referencing a font the reader lacks is substituted, and the substitution changes the pagination.
• Every font contains every glyph of the output language. Verify by rendering a sample containing the accented characters, capitals included, the currency symbols and any special punctuation, then looking at it.
• A missing glyph renders as a box, a blank or a substituted character. All three are invisible in the source and obvious in the render.
• Where the document mixes scripts, verify each script separately.

pdffonts document.pdf

Every row must show an embedded font. Any row showing a non-embedded font is a defect, not a warning.

4. Verification

Mandatory. Automated checks first, then the eyes, because the eyes catch what no check describes.

Automated

pdfinfo document.pdf                    # pages, size, title, author, language
pdffonts document.pdf                   # every font embedded
pdftotext document.pdf - | head -50     # text extractable, reading order sane
qpdf --check document.pdf               # structural integrity

Checks:

• Page count matches expectation. An unexpected extra page is a defect.
• Metadata present and correct: title is the title, not the filename.
• Language set, so screen readers pronounce correctly.
• Every font embedded.
• Text extractable. Nothing that should be text is an image.
• Extraction order matches reading order.
• File size proportionate. A 40MB text document means unoptimised images.
• Structure valid.

Visual

Automated checks pass on documents that are visibly broken. Render the pages and look at them.

pdftoppm -png -r 110 document.pdf page   # one image per page

Then inspect every page, or every page of a long document's first twenty plus a systematic sample plus every page containing a table or a figure.

Print

For anything that will be printed:

• Printed in greyscale, on paper, and read. Every distinction survives.
• Nothing enters the binding margin or the unprintable edge.
• Links show their target in a footnote or an annex.
• Double-sided pagination correct: sections start where intended.

Where printing is impossible, render at print resolution, convert to greyscale, and inspect. State that this was done instead of a physical print, rather than implying a print check that did not happen.

5. Reproducibility

A PDF produced once by hand is a PDF nobody can correct.

• The source is text and lives in version control. The PDF is an artefact.
• Generation is one command, recorded in the recipe.
• The recipe records the engine, its version, the fonts and the command.
• Regenerating from an unchanged source produces the same pages. Where the engine embeds a timestamp, the byte output differs and the pages do not; compare rendered pages, not bytes.
• Never edit the PDF by hand. Edit the source and regenerate, or the next regeneration silently discards the correction.

## Generation recipe
Engine:   weasyprint 62.3
Fonts:    Source Serif 4 2.100, Source Sans 3 2.045, both embedded
Source:   docs/handover.md, docs/print.css
Command:  make handover.pdf
Verified: 2026-08-11, 34 pages, all fonts embedded, pages rendered and inspected

6. Accessibility and size

• Set the document language. Without it, a screen reader guesses.
• Reading order must match visual order; verify by extracting the text.
• Images that carry information need alternative text where the engine supports it, and a caption in every case.
• Never distribute a scanned image of text as a document. It is unsearchable, inaccessible and unquotable.
• Compress images to their display size. A 4000px screenshot on a 600px column is 40 times the necessary bytes.
• Keep the file small enough to email. Where it cannot be, split it or link the annexes.

7. Protocol

1. Confirm the content passed the document-core gate and the layout passed document-design.
2. Select the engine with section 1. Verify it is installed and record its version.
3. Verify font glyph coverage for the output language by rendering a sample and looking at it.
4. Build the structure of section 2 and set the metadata.
5. Generate.
6. Run the automated checks of section 4.
7. Render the pages to images and inspect them. This step is not optional and is not replaced by the automated checks.
8. Fix defects in the source, never in the PDF, and regenerate.
9. Re-inspect the pages the fixes touched, plus the pages after them, because a pagination fix moves everything downstream.
10. Perform the print check where the document will be printed.
11. Record the recipe and the verification report.
12. Name the file as an index entry and deliver.

8. Auto-critique

Score 0 to 5: engine chosen from the document and verified installed, fonts embedded and glyph coverage checked by rendering, structure complete, metadata correct, automated checks run, pages rendered and actually inspected, defects fixed in the source, re-inspection after pagination changes, print check where applicable, recipe recorded and reproducible.

Threshold: no axis below 3, average at least 4. For a document leaving the organisation, average at least 4.3.

Automatic failure: delivering a PDF whose pages were never rendered and looked at, a non-embedded font, a hand edit to the PDF, or a contents page whose numbers were not regenerated after the final edit.

9. Interfaces

• Upstream: document-design, technical-writing, user-documentation, report-writing, administrative-writing.
• Downstream: self-critique, client-handover.
• Related: document-core section 7 gates 9 to 11 are executed here.