> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blinkpdf.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Themes: Curated Design Presets for Every Document

> Pick a curated design theme with a single field. Blink PDF ships 15 presets for reports, blogs, academic papers, docs, and corporate documents — each a bundle of typography, page geometry, furniture, numbering, and styling rules.

A theme is a curated design preset you apply with one field. Instead of hand-authoring typography, page geometry, furniture, numbering, and styling `rules` for every document, set `theme` and the server resolves it to a fixed bundle — then merges your own settings on top. Blink PDF ships **15 themes** across five categories, and the default (`report-clean`) is the plain engine output, so you only opt into a look when you name one.

<Note>
  Picking a theme never lets the server read your Markdown — the bundle is deterministic and applied blindly. Theme fonts are **bundled and hosted**, so themes are identical on every plan; the only plan differences are volume, rate, and the free-tier watermark, never typographic quality.
</Note>

## The `theme` Field

<ParamField body="theme" type="string" default="report-clean">
  The slug of a curated design preset (see the catalog below). Resolved server-side to a fixed bundle of typography, page, furniture, numbering, and rules, then merged **under** your own `typography` / `page` / `furniture` / `rules` — your values win per field. Omitting the field, or passing an unknown slug, applies `report-clean`.
</ParamField>

```json theme={null}
{
  "markdown": "# Quarterly Review\n\nRevenue is up 18% year over year.",
  "theme": "report-executive"
}
```

## Theme Catalog

The 15 themes, in slug order. `report-clean` is the default. Discover the same catalog programmatically at [`GET /v1/themes`](#discovering-themes) or through the MCP `list_themes` tool.

| Slug               | Category  | Use it when                                    |
| ------------------ | --------- | ---------------------------------------------- |
| `report-clean`     | report    | Generic report or deep-dive; the clean default |
| `report-executive` | report    | 1–2 page executive brief or summary            |
| `report-data`      | report    | Report dense with tables and KPIs              |
| `blog-modern`      | blog      | Casual web post or article                     |
| `blog-dark`        | blog      | Screen-first dev post on a dark sheet          |
| `blog-editorial`   | blog      | Long-form magazine-style narrative             |
| `academic-classic` | academic  | Traditional numbered journal paper             |
| `academic-modern`  | academic  | Modern preprint or working paper               |
| `thesis`           | academic  | Thesis or long monograph with chapters         |
| `docs-light`       | docs      | README, guide, or technical docs               |
| `docs-dark`        | docs      | Terminal-tone docs or notes                    |
| `api-reference`    | docs      | API/endpoint reference                         |
| `corporate`        | corporate | Formal company report or memo                  |
| `proposal`         | corporate | Proposal, quote, or SOW                        |
| `invoice`          | corporate | Invoice or receipt                             |

<Info>
  `report-clean` has an empty delta — requesting it, or sending no `theme` at all, leaves the rendered output byte-for-byte identical to the engine defaults. It exists so you can name the default explicitly.
</Info>

## What a Theme Controls

Each theme contributes up to six dimensions. Most of the visual identity lives in the `rules` array (colors, sizes, per-depth headings, code blocks, tables, blockquotes); a handful of themes also set fonts, page geometry, furniture, numbering, or a PDF outline.

| Dimension                           | Example themes that set it                                                      |
| ----------------------------------- | ------------------------------------------------------------------------------- |
| **Typography** (bundled fonts)      | `blog-editorial`, `academic-classic`, `academic-modern`, `thesis`, `proposal`   |
| **Page** (margins, dark background) | `report-executive`, `proposal` (margins); `blog-dark`, `docs-dark` (dark sheet) |
| **Furniture** (page folios)         | `thesis`, `corporate`, `proposal` (all with `omitFirstPage`)                    |
| **Heading numbering**               | `academic-classic`, `thesis`                                                    |
| **PDF outline** (bookmarks)         | `docs-light`, `thesis`                                                          |
| **Styling rules**                   | Every theme except `report-clean`                                               |

## Precedence: Your Settings Always Win

A theme layers **under** your request body — it never overrides anything you set explicitly:

* `typography`, `page`, and `furniture` are deep-merged with **you winning per field**.
* `numbering` and `outline` are taken from your body whenever you set them at all.
* The theme's `rules` are **prepended** before yours, so on any conflicting cascade leaf your later rule wins.

A theme expresses nothing you could not author by hand.

<Warning>
  **Fonts are all-or-nothing.** If your request declares any font source — `fontStack` with a weighted family, `googleFontsUrl`/`googleFontsUrls`, or `typography.body` / `typography.heading` — the theme's hosted typography is **dropped wholesale**, so a theme font is never mixed with your own. Everything else in the theme (page, furniture, numbering, outline, rules) still applies. See [Fonts & Typography](/configuration/fonts-layouts).
</Warning>

## Unknown or Omitted Themes

Theme resolution never fails a render. If you omit `theme` or pass an unknown slug, the base `report-clean` theme is applied instead:

* **Omitted** → `report-clean` is applied silently.
* **Unknown slug** → `report-clean` is applied and the response carries an `X-Render-Theme-Fallback` header (for example `applied=report-clean; requested=report-dat; didYouMean=report-data`), plus a nearest-match `didYouMean` suggestion when one is within edit distance. A theme fallback also flips `X-Render-Rendered-As-Requested` to `false`.

On the [validate](/api-reference/overview#validate-before-render) endpoint the same outcome is surfaced structurally as a `resolvedTheme` object (`slug` / `requested` / `fellBack` / `didYouMean`) instead of a header.

## Discovering Themes

`GET /v1/themes` returns the full catalog as JSON so tools and agents can list themes without hard-coding the slugs:

```json theme={null}
{
  "version": "1",
  "default": "report-clean",
  "themes": [
    { "slug": "report-clean", "category": "report", "useWhen": "generic report or deep-dive; the clean default", "isDefault": true },
    { "slug": "report-executive", "category": "report", "useWhen": "1–2 page executive brief or summary", "isDefault": false }
  ]
}
```

The response is cacheable — it carries a version-keyed `ETag`. AI agents connected through the [MCP server](/mcp/overview) can call the equivalent `list_themes` tool, which returns the same `{ version, default, themes[] }` shape.

<Tip>
  Combine a theme with your own overrides freely: start from `report-data` for a KPI-heavy report, then add a `page.margin` or a `rules` entry to fine-tune — your settings layer cleanly on top of the preset.
</Tip>