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

# Page Settings

> Set a page title, layout, theme, and other per-page settings using YAML frontmatter at the top of a page.

A page's settings live in a block of YAML **frontmatter** at the top of the file, delimited by `---`. They set the page's title and can override the project-wide defaults (from [`evidence.config.yaml`](/features/project-settings)) for that page only.

```markdown theme={null}
---
title: My Page
page_width: full
cards: true
sidebar_position: 2
auto_refresh: 300000
---

# Page content here
```

Most pages only need a `title`. Add other keys to override a setting for that page; anything you leave out is inherited from the project.

## Supported keys

| Key                 | Type                | Description                                                                                       |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------------- |
| `title`             | string              | The page's display name (used in the sidebar, breadcrumbs, and tab title).                        |
| `page_width`        | `article` \| `full` | Override the project's page width for this page.                                                  |
| `cards`             | boolean             | Override whether components are wrapped in cards.                                                 |
| `table_of_contents` | boolean             | Override whether the table-of-contents sidebar is shown.                                          |
| `auto_refresh`      | number (ms)         | Override how often the page re-runs its queries. `0` disables it.                                 |
| `sidebar_position`  | number              | Order the page within its sidebar group (lower numbers first). Page-only — not a project default. |
| `icon`              | string              | The icon shown next to the page in the sidebar. Page-only.                                        |
| `theme`             | object              | Per-page [theme](/features/themes) overrides (colors, palettes, scales). See below.               |
| `type`              | `partial`           | Marks the file as a [partial](/core-concepts/partials). Only used for partials.                   |
| `workflow`          | object              | Turns the page into a periodic report. See [`workflow.period`](#workflow-period) below.           |

### Inheritance

The layout keys (`page_width`, `cards`, `table_of_contents`, `auto_refresh`) override the project's `layout` in [`evidence.config.yaml`](/features/project-settings) for that page.

`sidebar_position` and `icon` are page-only settings; they have no project-wide default.

### `theme`

Per-page theme overrides are nested under `theme:`, mirroring the structure of [`theme.yaml`](/features/project-settings#theme-yaml). Anything you set here overrides the project theme for this page only; anything you leave out is inherited.

```markdown theme={null}
---
title: Revenue
theme:
  colors:
    base:
      light: '#ffffff'
      dark: '#0b1020'
  colorPalettes:
    default:
      light: ['#154886', '#45a1bf']
---
```

### `workflow.period`

Adding a `workflow.period` block turns the page into a **periodic report**: a period picker appears at the top right, and the selected period is available as the `period` variable.

````markdown theme={null}
---
title: Monthly Operations Report
workflow:
  period:
    grain: month
    periods: 12
---

# {{ period.label }} Operations Review

```sql monthly_orders
select count(*) as orders
from demo.daily_orders
where order_date {{ period.between }}
```
````

| Key       | Type                                              | Description                                                              |
| --------- | ------------------------------------------------- | ------------------------------------------------------------------------ |
| `grain`   | `day` \| `week` \| `month` \| `quarter` \| `year` | The calendar period each entry covers. Defaults to `month`.              |
| `periods` | number                                            | How many periods the picker offers, between 1 and 500. Defaults to `12`. |

Only **complete** periods are offered — the period in progress never appears, so a published report doesn't change under the reader while its period is still running. The most recent complete period is selected by default, and the selection is kept in the URL so a link points at a specific period.

`period` behaves like any other [input](/core-concepts/variables#in-inputs):

| Property             | Example                                                 | Description                                                           |
| -------------------- | ------------------------------------------------------- | --------------------------------------------------------------------- |
| `period.between`     | `BETWEEN toDate('2026-07-01') AND toDate('2026-07-31')` | WHERE-clause fragment for the period. The default in SQL.             |
| `period.label`       | `Jul 2026`                                              | Display label. The default in markdown and column attributes.         |
| `period.start`       | `toDate('2026-07-01')`                                  | First date of the period, as SQL. Use `start_label` in prose.         |
| `period.end`         | `toDate('2026-07-31')`                                  | Last date of the period, inclusive, as SQL. Use `end_label` in prose. |
| `period.start_label` | `Jul 1, 2026`                                           | First date of the period, formatted for display.                      |
| `period.end_label`   | `Jul 31, 2026`                                          | Last date of the period, formatted for display.                       |
| `period.key`         | `2026-07`                                               | Stable identifier for the period.                                     |
| `period.grain`       | `month`                                                 | The configured grain.                                                 |

`period.start` and `period.end` are SQL expressions for the active dialect — writing them in markdown prints `toDate('2026-07-01')`. Use `start_label` / `end_label` for text.

`workflow` is reserved for reporting settings; other keys under it are ignored for now.

## Frontmatter variables

Any key that isn't one of the settings above is treated as your own custom value and preserved as-is. This is how **page variables** are defined — in the same frontmatter block, alongside your page settings — and then referenced elsewhere on the page with `{{ $my_var }}`. See [Variables → In Frontmatter](/core-concepts/variables#in-frontmatter).