---
layout: layouts/base.njk
permalink: /presentation/themes/
title: Themes and layout
summary: The twelve colour slots, the thirteen style keys, the eight layout roles, and the four themes that ship with the presentation package.
section: Markdown Presentation
order: 2
---

A theme is a directory. `theme.yml` is required; `styles.yml`, `layouts.yml` and
`template.pptx` are optional.

```text
themes/corporate-dark/
├── theme.yml      required
├── styles.yml     the Word half's vocabulary — the renderer does not read it
├── layouts.yml    which PowerPoint layout each role maps to
└── template.pptx  optional, a path
```

## `theme.yml`

| Key | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | string | — | **required**, non-empty |
| `description` | string | `null` | |
| `author` | string | `null` | |
| `dark` | boolean | `false` | boolean only — `dark: yes` is refused |
| `colors:` | mapping | see below | `#rrggbb`, stored upper-cased |
| `fonts:` | mapping | Calibri / Calibri / Consolas | `heading`, `body`, `mono` |
| `style:` | mapping | see below | the geometry |

`dark: yes` being refused is not pedantry. YAML 1.1 truthy strings are what make a theme written
by hand behave differently from one written by a machine, and this one is for machines.

## The twelve colour slots

```text
dk1 lt1 dk2 lt2 accent1 accent2 accent3 accent4 accent5 accent6 hlink folHlink
```

Defaults: `#000000` `#FFFFFF` `#44546A` `#E7E6E6` `#4472C4` `#ED7D31` `#A5A5A5` `#FFC000`
`#5B9BD5` `#70AD47` `#0563C1` `#954F72`.

Four read-friendly aliases are accepted: `dark1`, `light1`, `dark2`, `light2`, `hyperlink`,
`followedHyperlink`.

`dark: true` swaps four of them — the page becomes `dk1`, the ink `lt1`, the panel `dk2`, the
subtle ink `lt2` — which is why the same theme can be dark without being a second theme.

## `style:` — the geometry

| Key | Type | Default | Minimum |
| --- | --- | --- | --- |
| `margin` | int, px | 40 | 1 |
| `gutter` | int, px | 20 | 1 |
| `block` | int, px | 12 | 1 |
| `rule` | int, px | 2 | 1 |
| `body` | int, pt | 16 | 1 |
| `title` | int, pt | 28 | 1 |
| `cover` | int, pt | 40 | 1 |
| `section` | int, pt | 44 | 1 |
| `headings` | list of int, pt | `[22, 20, 18, 16, 14]` | each ≥ 1 |
| `leading` | number | 1.2 | 1.0 |
| `heading-weight` | `bold` or `regular` | `bold` | |
| `heading-ink` | `ink` or `accent` | `ink` | |

## Layout roles

Eight, and only these:

```text
title  content  two-column  section  blank  image-text  image-title  image-slide
```

`blank` and `image-slide` have no title box. `layouts.yml` maps each role to a layout name in the
master — the file may be a bare mapping or nested under a single `layouts:` key.

Only the roles a deck actually uses are built, so a ten-slide deck does not carry eight masters.

## The four that ship

| Theme | Margin | Block | Body | Headings | Leading | Weight | Ink |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `default` | 40 | 12 | 16pt | 22/20/18/16/14 | 1.2 | bold | ink |
| `corporate-dark` | 48 | 16 | 18pt | 26/23/21/19/17 | 1.32 | bold | **accent** |
| `minimal` | 64 | 14 | 17pt | 23/22/21/20/19 | 1.12 | **regular** | ink |
| `dense` | 28 | 8 | 13pt | 17/16/15/14/13 | 1.1 | bold | ink |

`minimal` has more margin and less ink; `dense` has less margin and smaller type. Those are the
two axes a deck is usually fighting over, and they are separate keys so you can move one.

## Resolution order

1. an explicit path — anything containing `/`
2. `<workingDirectory>/themes/<name>`
3. the package's own `themes/<name>`

There is **no silent fallback to `default`**. A name that does not resolve raises `ThemeNotFound`
and lists every theme that does. A deck that came out looking like something other than what was
asked for is worse than a deck that did not build.

## Word themes

The Word half has themes too, and they are the other shape: a directory with `theme.yml` —
`name`, `description`, `author`, and `name` required — and an optional `styles.yml` holding the
same slot names the [Word configuration](/word/configuration/) page lists. Four ship:
`default`, `minimal`, `corporate`, `report`.

A theme is a **starting point**, not a replacement: your own `styles:` sits on top of it, and
which keys you wrote is remembered so a partial override does not silently discard the rest.