Templates & styles

template = base theme  +  style overrides (accent, fonts)  +  page format

You reference a template by its slug or id when rendering — via the REST API, an MCP create_pdf call, or the dashboard editor.

Base themes

Five built-in themes ship with every deployment (web, API, MCP). They're bundled modules, so they're identical everywhere.

Use a theme directly on a render with theme: "editorial", or as the base for a template.

Style overrides

Templates layer a small, sanitized set of tweaks over the base theme. Only these fields exist, and each is validated before it touches the CSS:

Fonts

Font values are preset keys, not arbitrary font names. There are two groups.

System stacks — always available, no download:

Self-hosted Google fonts — embedded into the PDF as @font-face (only the fonts a render actually uses are embedded):

Formats

Built-in templates

Every deployment ships these ready-to-use system templates. Render with any slug directly — no setup. (They're read-only starting points; fork/clone in the dashboard to customise.)

List them live (plus your own) with GET /api/v1/templates or the MCP list_templates tool.

Creating templates

Three ways, all producing the same record:

• Dashboard → Templates (https://inkrun.dev/templates): a visual builder for theme, accent, fonts, and format.
• REST API → POST /api/v1/templates — see API · Templates.
• MCP → the create_template tool, then render with the returned slug.

curl "https://inkrun.dev/api/v1/templates" \
  -H "Authorization: Bearer $INKRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Proposal",
    "themeName": "default",
    "format": "A4",
    "styles": { "accent": "#1F6FEB", "fontHeading": "sans", "fontBody": "serif" }
  }'

Style precedence (how the CSS layers)

At render time the CSS is composed in this order (later wins):

base theme CSS  <  custom-theme tokens  <  template style overrides

And at the request level, an explicit theme/format on the render call overrides whatever the template specifies. Style overrides work by injecting a :root { --accent: …; --font-body: …; } block after the theme CSS, so they win by source order — the built-in themes are driven entirely by these CSS variables.

Custom themes & cover pages

Beyond the tweakable style options, the dashboard (Themes, https://inkrun.dev/themes) lets you fork a built-in theme into a fully custom one:

• Theme tokens — palette, typography, headings, spacing, page margins, and header/footer, edited visually. (Hex-only colours and preset fonts — no raw CSS, by design.)
• Cover page — an optional designed first page built in a visual editor. Placeholders (e.g. title, subtitle) are filled from the document's frontmatter. Cover images are validated raster data (PNG/JPG, ≤300 KB; no SVG) and the cover renders full-bleed.

A custom theme has its own slug/id (thm_…). Render on it directly (theme: "my-brand"), or base a template on it (themeName: "my-brand").

Frontmatter

A leading --- YAML block is stripped before rendering and used to fill cover placeholders and the document title:

---
title: Q2 Revenue Report
subtitle: FY2026
---

# Q2 Revenue

Strong quarter…

• Scalars only, bounded sizes. Values bind to cover-page placeholders and the PDF <title>.
• The frontmatter title: is used as the render's title when the request doesn't supply one.
• A malformed or oversized block is not swallowed — it renders as ordinary Markdown so you can see it.

Charts

Add a chart by including a fenced code block tagged chart: a key: value settings block, a --- separator, then a GitHub-style Markdown data table.

```chart
type: bar
x: Quarter
y: Revenue, Costs
title: 2026 Performance
stacked: false
---
| Quarter | Revenue | Costs |
| ------- | ------- | ----- |
| Q1      | 120     | 80    |
| Q2      | 180     | 95    |
```

Settings

Rules

• Every cell under a y column must be numeric. Thousands separators and trailing units like % or $ are tolerated; any non-numeric y cell makes the whole fence fall back to a plain code block.
• At least one data row is required.
• Charts render as static inline SVG sized to fit the page — offline and deterministic, no interactivity.

Over MCP, the get_chart_syntax tool returns this spec verbatim.