# epub@0.1

**Status:** normative. **Inherits:** [`../conventions.md`](../conventions.md). **Schema:** [`schema.json`](schema.json). **Fixtures:** [`fixtures/`](fixtures/). **Owns diagnostic codes:** `MDTO1600`–`MDTO1699`.

This is a content model, not the shared task item model. It does not reinterpret task checkbox state.

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

## 1. Purpose

`epub@0.1` describes a reflowable book: level-2 headings are chapters, ordinary Markdown carries the manuscript, and explicit publication metadata travels with its assets.
The file stays readable, diffable, and authoritative in any Markdown viewer.

---

## 2. Grammar

### 2.1 Envelope

```yaml
---
markdownto: epub@0.1
title: The art of noticing
author: Alex Rivera
language: en
---
```

Shared envelope and preservation rules apply. Unknown keys are preserved and inert. Settings are validated without network access.

### 2.2 Manuscript and publication metadata

One optional leading `#` names the book. Every nonempty, case-insensitively unique `##` starts a chapter and must have body content; lower headings are subsections. Content before the first chapter is invalid. GFM paragraphs, images, tables, lists, code, and quotes remain content; raw HTML is inert source. No executable extensions are allowed.

`author`, `language`, `identifier`, `cover`, and `modified` are optional string keys. Language defaults to `en` and uses a hyphenated language tag such as `en-GB`. `identifier` is a stable publication identifier; when omitted, a deterministic source digest supplies one. `cover` names a local PNG, JPEG, or GIF. `modified` is an authored UTC revision timestamp (`YYYY-MM-DDTHH:MM:SSZ`). When omitted, packaging uses the reproducible baseline `2000-01-01T00:00:00Z`; it does not claim a filesystem modification date. Set this metadata for a published edition. A first all-field paragraph is reserved direction; unknown fields are inert.

The build produces EPUB 3: first uncompressed `mimetype`, container, package metadata, navigation document, ordered chapter XHTML, stylesheet, and referenced local images. Assets must resolve within the manuscript directory after symlinks; unsupported or missing assets refuse the whole build. No remote asset is fetched. External hyperlinks remain links. `#chapter-N` links target the corresponding one-based chapter. Images require alternate text in authored Markdown for accessibility. Readers can reflow type without changing manuscript state.

Build output is deterministic for identical source and asset bytes: stable entry order, timestamps, identifiers, and metadata. The package contains no scripts, network dependencies, or generated prose. EPUB output and HTML reader preserve chapter order and authored content. The exporter must validate package structure and XML before delivery; visual/reflow inspection is an additional quality gate.

### 2.3 Canonical IR

The IR sits at `result.epub`, beside `result.document`. It carries the envelope, ordered source-positioned content, parsed direction, effective settings, and domain data defined in `schema.json`. Source offsets address edits, never an independently parsed renderer copy. Parse and serialize reproduce the source byte for byte.

### 2.4 Diagnostics

| Code | Severity | Meaning |
| --- | --- | --- |
| `MDTO1600` | error | No sections. |
| `MDTO1601` | error | Invalid heading or content before a section. |
| `MDTO1602` | error | Invalid settings or direction. |
| `MDTO1603` | error | Invalid required content structure. |
| `MDTO1605` | error | Duplicate section or option identity. |

## 3. Rationale

**One heading axis.** `##` has one domain meaning, so authoring, validation, rendering and operations agree. Familiar Markdown remains useful without this runtime.

**Explicit state.** Meaningful user input belongs in the file; selected views and transient controls do not. Renderers never invent missing facts. Shared safe rendering treats executable-looking content as data.

**Small portable surface.** This format chooses bounded semantics over arbitrary executable extensions. Its companion skill teaches editorial judgment without making taste a validation rule.

## 4. Examples

````markdown
---
markdownto: epub@0.1
title: The art of noticing
author: Alex Rivera
language: en
---

## Begin where you are

Attention starts with the things already around you.
````

See the valid fixtures for a complete, realistic example and edge cases. Invalid fixtures define the exact errors, not examples to imitate.

## 5. Verb reference

`epub@0.1` owns the vocabulary **build**.

| Verb | Signature | Source edit |
| --- | --- | --- |
| `build` | `mdto epub build [--out book.epub]` | Package a local, reflowable EPUB 3 book and its assets. |

### Common flags and editing guarantees

`--file <path>` selects the source; `--json` uses the `mdtoJson: 1` envelope; `--help` describes the verb. Mutation verbs also accept `--expect <hash>` and `--dry-run`; they validate the complete batch and refuse stale or invalid results without writing. Question/criterion references are one-based numbers or exact case-insensitive titles. Updated fences use JSON escaping and preserve all untouched bytes. Repeating an already-satisfied mutation is a no-op. Builds accept `--out`; outputs never replace the source. Cross-spec conversion is refused when meaning would have to be invented; use explicit authoring instead.