Document metadata
Document metadata
Frontmatter starts at the beginning of the file with --- and closes with --- or .... Local drafts need no metadata. Publication requires a nonempty title, a description and a valid version; a missing one is publish.metadata. A source marks its format with format: rmd/1; a newer major version is the error frontmatter.format. A version is a quoted string MAJOR.MINOR.PATCH with an optional -prerelease, under SemVer 2.0.0 numeric rules: no leading zeros, no +build metadata, no surrounding whitespace, at most 64 bytes. A YAML number such as 1.0 is frontmatter.type (quote it), and an invalid string is frontmatter.version; both leave the version unset, so publishing fails with publish.metadata.
---
title: Revenue rose in Q3
description: Retained customers drove most of the improvement.
version: 0.0.1
author: Daniel Vecera
date: 2026-10-04
styles: [scientific]
---
<!-- registry:begin frontmatter -->
| Field | Type | Required | Default | Meaning |
| --- | --- | --- | --- | --- |
| `title` | text | | | The report title; publishing requires it, and a draft without one shows `Untitled report`. |
| `description` | text | | | The deck under the title; publishing requires it. |
| `author` | text | | | The author, as plain text. |
| `date` | text | | | The report's date, `YYYY-MM-DD` or RFC 3339. |
| `slug` | text | | | The address name the report is published under. |
| `version` | text | | | The semver version; publishing requires it. |
| `lang` | text | | `en` | The report's language as a BCP 47 tag: it sets the page language, quotes and number separators. |
| `format` | text | | `rmd/1` | The format version the report was written for; a newer major version is refused. |
| `tags` | text or list of text | | | Labels for the report; one string is one tag. |
| `styles` | text or list of text | | | Style names or report-relative style files; the first is the base and later ones override it. One string is one entry. |
| `title_image` | text or mapping | | | The header image; a bare source string stands for `{src}`. |
| `title_image.src` | text | yes | | The image: a report-relative path, a data address or a credited Unsplash photo address. |
| `title_image.alt` | text | | | The text alternative. |
| `title_image.caption` | text | | | The caption under the image. |
| `title_image.fit` | one of `contain`, `cover` or `fill` | | `contain` | How the image fills its box. |
| `title_image.width` | whole number | | | The image width in pixels; a positive whole number. |
| `title_image.height` | whole number | | | The image height in pixels; a positive whole number. |
| `title_image.credit` | mapping | | | The photo credit; an Unsplash photo needs one. |
| `title_image.credit.author` | text | yes | | The photographer's name. |
| `title_image.credit.author_url` | text | | | The photographer's profile; required on an Unsplash photo. |
| `title_image.credit.source` | text | | | The site the photo comes from. |
| `title_image.credit.source_url` | text | | | The photo's page on the source site. |
| `title_image.color` | any value | | | A #rrggbb colour that fills the box until the photo loads. |
| `publish` | any value | | | Publication metadata for RichView Publish; other hosts ignore it. |
| `tabs` | mapping | | | Splits the body into tab panels at heading anchors. |
| `tabs.default` | text | | | The panel shown first; an omitted or unknown string selects the first panel. |
| `tabs.export` | one of `all` or `active` | | `all` | Whether printed and PDF output holds every panel or only the active one. |
| `tabs.panels` | list of mapping | yes | | The panels, in document order; at least one. |
| `tabs.panels[n].id` | text | yes | | The panel id, unique, using the report slug grammar; it names the #tab link. |
| `tabs.panels[n].label` | text | yes | | The text on the panel's tab. |
| `tabs.panels[n].from` | text | yes | | The explicit heading anchor where the panel starts. |
<!-- registry:end -->
## The evidence
```chart
type: bar
title: Revenue increased across both months
data:
inline:
- month: Jul
revenue: 100
- month: Aug
revenue: 140
encoding: {x: month, y: revenue}
```
| Field | Accepted value | Behavior |
|---|---|---|
title | string | Report heading and HTML title; draft fallback is Untitled report. Required for publication. |
description | string | The one deck under the title. Required for publication. |
version | strict SemVer string, no build metadata | Immutable publication identity; start at 0.0.1. |
author, date | strings | Escaped display text. A date is YYYY-MM-DD or an RFC 3339 timestamp; author text is not evaluated as Markdown. |
slug | 1-80 characters of a-z, 0-9 and -, with no leading, trailing or double hyphen | Publication slug. An invalid value warns as frontmatter. and fails publishing as publish.; it is never rewritten. Without slug it is derived from the title. |
lang | BCP 47 tag | The report language: lang on the page, calendar labels and the decimal and grouping separators of tables, metrics and charts. |
format | rmd/<major> | The format marker; a newer major version is refused, and retired fields require source edits. |
tags | string or string array | Retained report metadata; a bare string is a list of one. |
styles | string or ordered string array | Builtin names or resource references, followed by caller/CLI style overrides. |
title_ | source string or image mapping | Header image; object form supports the image block fields, including credit. |
publish | mapping | Publication settings read by the host. |
tabs | mapping | Splits the body into views that readers switch between. See Tabs. |
Retired frontmatter keys fail with their own code and replacement. Renamed and removed names lists these from the registry. Repair the named fields in source; no migration command is exposed.
An unknown frontmatter key stays in the metadata and warns frontmatter.unknown-key, naming the nearest known key. Malformed known fields produce diagnostics and degrade gracefully. Numeric text is not substituted for metadata strings.
Tabs
tabs splits one report’s body into views that readers switch between, such as Overview, Sales and Customers. It is optional: reports without it render exactly as before.
---
tabs:
default: overview # optional; otherwise the first panel
export: all # all (default) | active
panels:
- { id: overview, label: Overview, from: overview }
- { id: sales, label: Sales, from: sales }
- { id: customers, label: Customers, from: customers }
---
## Overview {#overview}
Summary.
## Sales {#sales}
Sales detail.
## Customers {#customers}
Customer detail.
Each panel starts at a heading with an explicit anchor, such as ## Sales {#sales}, and runs to the next panel’s heading or the end of the body. An explicit heading id is kept only when a panel names it; a generated id alone cannot start a panel. Content before the first panel stays above the tabs and is never hidden. Prose, rich fences, charts and tables inside a panel behave as anywhere else.
Panel IDs and explicit heading anchors use the report slug grammar. The panel ID names deep links such as #tab=sales; panels list their starting anchors in document order. The generated frontmatter reference above defines the fields and value types.
The interactive report, which loads the browser runtime, renders a tablist of buttons and tabpanel sections. Inactive panels carry hidden but stay in the DOM, so chart state and readouts survive a switch. Clicking a tab or pressing ←/→ (wrapping), Home or End selects it and moves focus with the selection; Tab moves on to the panel content. Selection replaces the URL fragment with #tab=<id> without adding history entries, and loading or changing to a known #tab=<id> selects that panel. Charts in a hidden panel mount when the panel is first shown.
The HTML report holds every panel in order. The runtime adds the tab buttons and hides inactive panels when it mounts; before that, without JavaScript or when the runtime cannot start, every panel remains readable without buttons. On narrow screens the tab list scrolls horizontally on its own.
A malformed tab configuration, including invalid field types or an unsupported export value, warns and renders the complete body without tabs. Missing, repeated or out-of-order starting anchors follow the same recovery. An unknown string default remains recoverable: it warns and selects the first panel.