---
name: markdownto-pdf
description: Author or revise Markdown To publications with readable structure and deliberate page design.
---
# Markdown To pdf
## Contract and workflow
Read `mdto spec pdf` (or the adjacent `SPEC.md` in a checkout) and the
[shared conventions](https://markdownto.ai/specs/conventions.md) before authoring or
repairing content. Outside a checkout, use the [published spec](https://markdownto.ai/specs/pdf.md).
This skill accompanies `[email protected]`. The spec and its fixtures govern conformance;
editorial advice below is non-normative and should adapt to the user's brief.
If the source declares another version, obtain its matching contract before changing it.
Use `markdownto: [email protected]`. Read the supported page, margin, style, and contents settings
before choosing frontmatter; unfamiliar keys do not become layout controls. Ordinary
GFM content remains the source. Inspect `mdto pdf build --help` for the available build
path. HTML validation alone cannot establish the quality of the final paginated PDF.
## Content quality
Lead with the document's purpose and give each section a job. Use a heading hierarchy
that explains the argument, captions that interpret figures, and tables only for real
comparisons. Keep evidence close to claims. Review the actual PDF for clipped tables,
awkward page breaks, orphaned headings, legibility, and working links; fix the source and
rebuild. Match the user's length and visual brief rather than padding to fill pages.
## Check and deliver
Validate the file with `mdto validate <path>` before editing existing content and again
after changes. Read diagnostics against the spec's rationale; preserve meaning when
repairing syntax. Prefer spec-owned verbs for edits they support, checking their current
`--help`; otherwise make a focused source edit, preserving unrelated content and IDs.
Render with `mdto render <path>` and inspect the result when available. Validation checks
structure, not editorial quality: review the content against the user's purpose as well.
Without the CLI, use the contract and examples and report that validation was not run.
Deliver the Markdown source and any requested artifacts, stating what was actually checked.
Give this guide to your agent, or read it as an author. It covers workflow and editorial judgment; the specification defines conformance.
Contract and workflow
Read mdto spec pdf (or the adjacent SPEC.md in a checkout) and the shared conventions before authoring or repairing content. Outside a checkout, use the published spec. This skill accompanies [email protected]. The spec and its fixtures govern conformance; editorial advice below is non-normative and should adapt to the user's brief. If the source declares another version, obtain its matching contract before changing it.
Use markdownto: [email protected]. Read the supported page, margin, style, and contents settings before choosing frontmatter; unfamiliar keys do not become layout controls. Ordinary GFM content remains the source. Inspect mdto pdf build --help for the available build path. HTML validation alone cannot establish the quality of the final paginated PDF.
Content quality
Lead with the document's purpose and give each section a job. Use a heading hierarchy that explains the argument, captions that interpret figures, and tables only for real comparisons. Keep evidence close to claims. Review the actual PDF for clipped tables, awkward page breaks, orphaned headings, legibility, and working links; fix the source and rebuild. Match the user's length and visual brief rather than padding to fill pages.
Check and deliver
Validate the file with mdto validate <path> before editing existing content and again after changes. Read diagnostics against the spec's rationale; preserve meaning when repairing syntax. Prefer spec-owned verbs for edits they support, checking their current --help; otherwise make a focused source edit, preserving unrelated content and IDs. Render with mdto render <path> and inspect the result when available. Validation checks structure, not editorial quality: review the content against the user's purpose as well. Without the CLI, use the contract and examples and report that validation was not run. Deliver the Markdown source and any requested artifacts, stating what was actually checked.