# timeline@0.1

**Status:** normative. **Inherits:** [`../conventions.md`](../conventions.md) — envelope,
preservation, safe rendering, and shared diagnostics. It has no items: a timeline point is a dated
narrative entry, not a task. **Schema:** [`schema.json`](schema.json). **Fixtures:**
[`fixtures/`](fixtures/). **Owns diagnostic codes:** `MDTO1100`–`MDTO1199`.

**Companion skill:** [Authoring and editorial guidance](https://markdownto.ai/specs/timeline.skill.md) (non-normative).

---

## 1. Purpose

`timeline@0.1` describes a **dated narrative**: each level-2 heading names a date and event, and the
Markdown beneath it carries the event's detail. The source remains a readable chronology; the HTML
lays those moments along one composed line without manufacturing dates or ordering.

---

## 2. Grammar

### 2.1 Envelope

```yaml
---
markdownto: timeline@0.1
title: A short history of the web
---
```

Only shared `title` and `id` are reserved. Unknown frontmatter remains preserved and inert.

### 2.2 Dated entries

`## YYYY-MM-DD — Title` opens one **timeline entry**. At least one is required (`MDTO1100`). The
date must be a real full-date (`MDTO1101`) and the title after the em dash must be non-empty
(`MDTO1102`). A plain hyphen is accepted for keyboards that cannot easily type an em dash; canonical
IR does not remember which separator was used.

One optional leading `#` document title is allowed. Every other heading level is `MDTO1103`.
Content before the first dated entry is `MDTO1104`. Entries stay in document order: chronology is
authored, never silently sorted.

### 2.3 Details and canonical IR

Every block until the next `##` is the entry's `details`: paragraphs, lists, blockquotes, tables,
code, and inert HTML source use the shared content block model. Empty details are legal; a concise
timeline may need only a date and title.

The IR sits at `result.timeline`, beside `result.document`, and carries ordered entries with
`date`, `title`, `details`, and source positions.

### 2.4 Diagnostics

| Code | Severity | Meaning |
|---|---|---|
| `MDTO1100` | error | Document has no dated entries. |
| `MDTO1101` | error | Entry heading has no real full-date and separator. |
| `MDTO1102` | error | Entry title is empty. |
| `MDTO1103` | error | Heading level is invalid. |
| `MDTO1104` | error | Detail content appears before the first entry. |

---

## 3. Rationale

**Why one entry per heading.** The date and event remain visible in every outline and each point can
carry rich detail without compressing prose into fields. `##` has one meaning: a point on the line.

**Why document order wins.** A personal chronology, product history, or research trail may use
reverse chronology or intentional flashbacks. The renderer exposes the order the author chose.

---

## 4. Examples

```markdown
---
markdownto: timeline@0.1
title: A short history of the web
---

## 1989-03-12 — The proposal

Tim Berners-Lee submits *Information Management: A Proposal* at CERN.

## 1991-08-06 — The first public website

The web project becomes available outside CERN.
```

---

## 5. Verb reference

`timeline@0.1` owns the vocabulary **list**.

| Verb | Signature | Source edit |
|---|---|---|
| `list` | `mdto timeline list [--from <date>] [--to <date>]` | None. Prints authored entries in document order, optionally filtered inclusively. |

### Common flags

`--file <path>` · `--from <YYYY-MM-DD>` · `--to <YYYY-MM-DD>` · `--json` · `--help`