# 25 — Book : le format `book` et book.recit.dev **Statut : proposé · Phase : P8 · Mis à jour : 02/11/2026.** Ce plan détaille la phase P8 de [06 · Feuille de route](/06-roadmap) : le format `book` (un livre en plusieurs fichiers Markdown, imprimé en PDF, publié en EPUB 3 et lu sur le web) et le site book.recit.dev. Il précise la spécification de [08 · Formats](/08-formats) §3 (lots B1 à B5) sans revenir sur les décisions acceptées : réglages à plat sans clé `book:`, `trim` devenu `pdf.page.size` en valeurs littérales, HTML intermédiaire produit par `@recit/book` et partagé par le PDF et l'EPUB, moteur `pagedjs` après le spike go/no-go PDF3.0, impression professionnelle (CMJN, PDF/X) hors périmètre ([15 · Export PDF](/15-export-pdf) §3.4 et §3.6). Deux passages des plans existants se contredisent sur le modèle du livre ; ils sont posés en questions ouvertes (§12, 1 et 3), avec une recommandation. Le PDF du livre appartient à PDF3 de `15` (PDF3.0 à PDF3.7). Ce plan ne redécrit pas la chaîne : il fixe ce que le livre lui fournit (le HTML intermédiaire, la vue imprimable, l'extension de schéma), et tout le reste du format. Les identifiants B0 à B7 sont ceux des lots du livre (`08` §3), pas les règles communes B1 à B11 de `06`. ## 1. Pourquoi **Un livre, un manuel ou une thèse s'écrit en plusieurs fichiers Markdown, et la même source donne un PDF prêt à imprimer, un EPUB valide et une édition web qu'on feuillette et qu'on cherche.** - **Le livre est le format long.** Un deck tient en un fichier ; un livre se répartit en chapitres, se relit chapitre par chapitre, se traduit chapitre par chapitre. Le format doit l'assumer : plusieurs fichiers, un ordre, des numéros, des renvois qui traversent les chapitres. - **Trois sorties, un seul HTML.** PDF, EPUB et web lisent le même HTML intermédiaire : un renvoi, une note ou une figure se résout une fois, et les trois sorties disent la même chose. - **Le client exigeant de la chaîne PDF.** Le livre est le seul format qui a besoin de titres courants, de pages paires et impaires, d'une table des matières et d'un index numérotés : il justifie le moteur `pagedjs` de `15`, qui profite ensuite au report. - **Des renvois qui ne cassent pas.** Un renvoi vers un `id` inconnu, un chapitre listé mais absent ou une image manquante est une erreur avec le fichier et la ligne, avant toute impression. Non-objectifs de P8 : impression professionnelle (CMJN, PDF/X, OutputIntent), écriture verticale CJK et sens de reliure RTL du lecteur PDF (`15` §3.8), parties et sous-parties (« Partie I ») au-dessus des chapitres, bibliographie gérée (CSL, BibTeX), EPUB 2 et Kindle (KF8, MOBI), édition collaborative. ## 2. Ce qui existe déjà et qu'on réutilise Relevé dans le code au 02/11/2026. | Élément | Où | Ce que le livre en fait | | --------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `StoryFormatSchema` (inclut `book`) | `packages/core/src/types/index.ts` | rien à ajouter : le format est déclaré | | `BookSourceSchema = genericSource("book")` | `packages/core/src/schema/source.ts` | remplacé par un schéma strict (§3.3) | | `resolveStoryFiles`, `mergeSidecar` | `packages/core/src/schema/assemble.ts` | résout chaque fichier du livre (entrée et chapitres) : jumeau, compagnon, variantes de langue, sans règle propre au livre | | `markdownToSource`, `sourceToMarkdown` | `packages/core/src/schema/convert.ts` | aller-retour de chaque fichier, sans code propre au format | | Test d'aller-retour de tous les exemples | `packages/core/src/__tests__/source-conversion.spec.ts` | couvre chaque fichier de `examples/book-*` dès lors qu'il déclare `format: book` (§3.2) | | Notes GFM (`[^1]`) | `remark-gfm` dans `createSlidePlugins` (`compile/compile-story.ts`) | déjà parsées ; le livre les renumérote par chapitre et les place selon la sortie | | `hast-util-to-html` 9 | lockfile | sérialise le HTML intermédiaire (HTML pour le web et le PDF, XHTML pour l'EPUB) | | Crochet de directives de `compileStory` | ajouté en P6 par R0 de [23 · Report](/23-report) | porte `::figure`, `:ref`, `:index`, `:::epigraph` ; le cœur ne garde que les noms (règle B4) | | Chaîne PDF, contrat d'impression | `@recit/paged`, `@recit/core/print` (PDF1, P6) | la vue imprimable du livre s'y branche ; `pagedjs` arrive avec PDF3.2 | | `exports.json` (`ExportManifestSchema`) | `@recit/core` (PDF0, P6) | gagne la variante `kind: "epub"` en B3 | | API de plugins : `getRoutes`, `getNavigation` | `packages/site/src/lib/core/plugins.ts` | l'édition web : une route par chapitre et la table des matières en sidebar, sans patch du framework de sites (§4.3) | | `StoryDocument` | `packages/integrations/site-stories/src/StoryDocument.tsx` | modèle du rendu d'un chapitre en page continue | | Fiche du format | `packages/tools/site-kit/src/formats.ts` (`status: "planned"`, `phase: "P8"`) | passe à `available` avec `site: "book"` en B5 | | `@recit/book` | `packages/formats/book` (stub privé, `scope:format`) | devient le package du format | Ce qui manque : `fflate` (zip de l'EPUB, nouvelle dépendance justifiée par `08` §0) et `pagedjs` (selon PDF3.0, `15` §4). Ni l'un ni l'autre n'est dans le lockfile. ## 3. Le modèle ### 3.1 Les fichiers d'un livre ``` examples/book-novella/ book.md # entrée : métadonnées, réglages, ordre des chapitres (pas de scène) book.fr.md # variante de langue de l'entrée (titre, sous-titre traduits) 00-preface.md # chapitre non numéroté 01-lorem.md 01-lorem.fr.md 02-ipsum.md 03-dolor.md images/map.svg recit.config.ts ``` `book.md` : ```md --- title: Lorem Ipsum author: Dolor Sit format: book lang: en cover: ./images/cover.svg chapters: - { file: 00-preface.md, numbered: false } - 01-lorem.md - 02-ipsum.md - 03-dolor.md front: [half-title, title, copyright, toc] back: [notes, index] publication: publisher: Lorem Press rights: © 2026 Dolor Sit, CC BY 4.0 pdf: page: size: { width: 6in, height: 9in } mirror: true toc: { depth: 2, pageNumbers: true } chapterStart: right footnotes: page --- ``` `01-lorem.md` : ```md --- format: book --- # Lorem ipsum :::epigraph{source="Consectetur, Adipiscing"} Lorem ipsum dolor sit amet. ::: Lorem ipsum dolor sit amet[^1], as the map shows (:ref[fig-map]). ::figure{src=./images/map.svg id=fig-map alt="Lorem valley seen from above"} The Lorem valley. :: --- id=lorem-night Sed do :index[eiusmod]{see=tempor} tempor incididunt. --- id=lorem-dawn break=page Ut enim ad minim veniam. [^1]: Duis aute irure dolor. ``` ### 3.2 Chapitres, sections, scènes - **Un chapitre est un fichier.** Son `id` est l'`id` de son frontmatter, sinon le nom du fichier sans préfixe numérique (`01-lorem.md` → `lorem`). Son titre est son premier H1 (`08` §3). - **Une scène est une section d'un chapitre** (`09-langues-et-json.md` §2.3) : `---` en ouvre une, la première commence au H1. Les scènes de tous les chapitres, dans l'ordre de `chapters`, forment les `scenes` de la `Story` compilée. Cette lecture contredit `08` §0 et `formats.ts`, qui disent « une scène = un chapitre » : question 1. - **Chaque fichier de chapitre déclare `format: book`.** Sans cela il se lirait comme un deck (défaut de `frontmatter.ts`), et le test d'aller-retour, qui parcourt tout `.md` de `examples/`, le traiterait comme tel. C'est une ligne par fichier ; question 2 pour l'inférer depuis l'entrée. - **Le fichier d'entrée n'a pas de scène.** Une préface ou une dédicace est un chapitre (`numbered: false`). Une scène dans `book.md` est une erreur avec sa ligne. - **Les `id` de scène sont uniques dans tout le livre**, puisque `:ref` traverse les chapitres. Un doublon est une erreur qui cite les deux fichiers et leurs lignes. Les `id` absents sont générés à partir de l'`id` du chapitre (`lorem-s2`), stables d'une langue à l'autre. - **Langues** : `book.fr.md` traduit l'entrée, `01-lorem.fr.md` traduit un chapitre ; la résolution et le repli sont ceux de `09` §3, fichier par fichier. `chapters` nomme les fichiers de base, sans locale, et reste identique dans toutes les langues (vérifié par `schema/parity.ts`). ### 3.3 Les schémas Dans `@recit/core` (zod/mini, comme `source.ts`), types dérivés par `z.infer`. `pdf` n'entre dans le schéma qu'avec PDF3.1 (`BookPdfOptionsSchema` de `15` §3.2), selon la règle « aucun champ avant sa phase ». ```ts // packages/core/src/schema/book.ts import * as z from "zod/mini"; export const ChapterEntrySchema = z.union([ z.string(), // "01-lorem.md", relative to book.md z.strictObject({ file: z.string(), /** false: preface, foreword, afterword — no chapter number */ numbered: z._default(z.boolean(), true), }), ]); export const FrontMatterPageSchema = z.enum(["half-title", "title", "copyright", "toc"]); export const BackMatterPageSchema = z.enum(["notes", "index"]); export const PublicationSchema = z.strictObject({ /** EPUB dc:identifier; a stable urn:uuid is derived from the slug when absent */ identifier: z.optional(z.string()), isbn: z.optional(z.string()), // checked: ISBN-13 with its check digit publisher: z.optional(z.string()), rights: z.optional(LocalizedSchema), edition: z.optional(z.string()), }); /** Settings of book.md (the entry); a chapter file has none */ export const BookSettingsSourceSchema = z.strictObject({ chapters: z.optional(z.array(ChapterEntrySchema).check(z.minLength(1))), front: z._default(z.array(FrontMatterPageSchema), ["title", "toc"]), back: z._default(z.array(BackMatterPageSchema), ["notes"]), cover: z.optional(z.string()), publication: z.optional(PublicationSchema), theme: z.optional(z.union([ThemeModeSchema, z.string(), ThemeConfigSchema])), /** Footnote numbering: restarts with each chapter (default) or runs through the book */ noteNumbering: z._default(z.enum(["chapter", "book"]), "chapter"), // pdf: BookPdfOptionsSchema — added by PDF3.1 }); export const BookSceneSourceSchema = z.strictObject(sceneFields); export const BookSourceSchema = z.strictObject({ ...storyFields, format: z.literal("book"), settings: z.optional(BookSettingsSourceSchema), scenes: z.array(BookSceneSourceSchema), }); ``` Les directives du livre suivent la règle B2 (des directives dans le `body`, validées par un schéma) : ```ts export const FigureBlockSchema = z.strictObject({ src: z.string(), id: z.optional(z.string()), // required to be referenced alt: z.optional(z.string()), // missing: a warning (tagged PDF, 15 question 6) width: z.optional(LengthSchema), }); export const RefDirectiveSchema = z.strictObject({ /** "page": adds "page N" in the PDF; the web and the EPUB keep the link */ show: z._default(z.enum(["label", "page", "both"]), "label"), }); export const IndexDirectiveSchema = z.strictObject({ see: z.optional(z.string()), // "see also" entry sub: z.optional(z.string()), // sub-entry of the term }); export const EpigraphBlockSchema = z.strictObject({ source: z.optional(z.string()) }); ``` | Élément | Rôle | Erreur (avec fichier et ligne) | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `chapters` | ordre des chapitres, numérotés sauf `numbered: false` | fichier listé mais absent ; fichier présent sans `format: book` | | H1 d'un chapitre | titre du chapitre, entrée de la table des matières, titre courant | chapitre sans H1, ou deux H1 | | `--- id=… break=page\|right` | section ; saut de page (`right` : page impaire) en PDF, sans effet sur le web | valeur de `break` inconnue | | `[^1]` | note, numérotée par chapitre ; en bas de page (PDF, `footnotes: page`), en fin de chapitre (web), `aside` (EPUB) | note appelée sans définition, ou définie sans appel | | `::figure{src id alt}` | figure numérotée par chapitre (« Figure 2.3 ») ; le contenu du bloc est la légende, localisée avec le `body` | image manquante ; `id` en double | | `:ref[id]{show}` | renvoi vers une figure, une section, un chapitre ou une note ; texte « Figure 2.3 », « Chapter 2 » | `id` inconnu | | `:index[term]{see sub}` | entrée d'index ; la page d'index liste les termes A–Z, triés par `Intl.Collator` de la locale | `see` vers un terme absent de l'index | | `:::epigraph{source}` | épigraphe en tête de chapitre | épigraphe ailleurs qu'en première section (avertissement) | | directives existantes | `:::callout`, Mermaid, KaTeX, code, tableaux GFM | celles d'aujourd'hui | `break` rejoint le registre des attributs de scène (règle B4) ; `figure`, `ref`, `index` et `epigraph` celui des directives (`DirectiveNameSchema`, créé en P6). `:index` n'est pas le `:term` de [12 · Glossaire et annuaire](/12-glossaire-annuaire) : `:term` lie une définition, `:index` marque une occurrence pour l'index du livre. Un même mot peut porter les deux. ### 3.4 Le jumeau JSON Chaque fichier a son jumeau `kind: "story"`, comme pour tout autre format. `book.json` reprend l'exemple de `15` §3.3 (réglages à plat dans `settings`, `"scenes": []`). Un chapitre : ```json { "$schema": "https://recit.dev/schema/v1/book.json", "kind": "story", "version": 1, "format": "book", "meta": {}, "scenes": [ { "id": "lorem", "body": "# Lorem ipsum\n\n:::epigraph{source=\"Consectetur, Adipiscing\"}…" }, { "id": "lorem-night", "body": "Sed do :index[eiusmod]{see=tempor} tempor incididunt." }, { "id": "lorem-dawn", "attrs": { "break": "page" }, "body": "Ut enim ad minim veniam." } ] } ``` - `chapters` peut nommer un `.json` aussi bien qu'un `.md` : un livre écrit entièrement en JSON (par un CMS ou un agent) est un livre complet. - L'épigraphe et les figures restent dans le `body`, sans champ `epigraph` ni `figures[]` : cela suit B2 et `08` §3, mais contredit la ligne `book` de `09` §2.3 (question 3). - `recit convert book.md --to json -o book.json` convertit l'entrée ; avec `--chapters`, il convertit aussi chaque chapitre à côté de son `.md`. ### 3.5 Le modèle compilé Le livre compile vers la `Story` commune. Ce qui lui est propre vit sous une clé dédiée (`02-architecture.md` §2), `story.book`, de type `BookOutline` défini une fois dans `@recit/core` (lu par `@recit/site-stories`, la CLI et le MCP) : ```ts export type BookOutline = { chapters: Array<{ id: string; title: string; number?: number; // absent when numbered: false file: string; scenes: { first: number; last: number }; // indexes into story.scenes }>; figures: Array<{ id: string; chapter: string; number: string; caption: string }>; index: Array<{ term: string; sub?: string; see?: string; targets: string[] }>; // anchor ids notes: Array<{ id: string; chapter: string; number: number }>; }; ``` Il est calculé par `assembleBook()` de `@recit/book/node`, qui lit l'entrée, résout chaque chapitre par `resolveStoryFiles` du cœur, compile, numérote et résout les renvois. Le cœur ne connaît toujours aucun format : il ne porte que les schémas et le type. ## 4. Le rendu ### 4.1 Le HTML intermédiaire `renderBookHtml(story, { target })` de `@recit/book` produit **une fois** un arbre hast par chapitre, plus les pages du pré et du post-texte (`front`, `back`), où renvois, numéros de figure et notes sont déjà résolus. Trois sérialisations seulement le distinguent : | Cible | Forme | Lue par | | ------- | --------------------------------------------------------------------------------------------------- | ------------------------------------ | | `print` | un document, pages nommées (`front`, `chapter`, `back`), notes en `float: footnote` si `pagedjs` | la vue imprimable (§4.2) | | `epub` | un XHTML par chapitre (`hast-util-to-html` avec `closeSelfClosing`, sans balise omise), `nav.xhtml` | `@recit/book/epub` (§4.4) | | `web` | une page par chapitre, notes en fin de chapitre avec retour à l'appel | `BookReader` et l'édition web (§4.3) | ### 4.2 PDF, par le plan 15 PDF3 de [15 · Export PDF](/15-export-pdf) fait le travail : spike go/no-go Paged.js (PDF3.0) sur `examples/book-novella`, `BookPdfOptionsSchema` (PDF3.1), moteur `pagedjs` derrière `PrintEngine` (PDF3.2), chapitres sur page impaire, numérotation romaine puis arabe et marges miroir (PDF3.3), titres courants, table des matières numérotée, notes et `target-counter` pour l'index et les renvois (PDF3.4), consommation du HTML intermédiaire (PDF3.5), un PDF par langue et artefacts marqués (PDF3.6), e2e (PDF3.7). Le livre fournit : - **la vue imprimable** (`@recit/book/print`, sur `?print=1`) : le HTML `print` du §4.1, la feuille des pages nommées propres au livre, et `whenPrintable()` une fois les images décodées et, avec `pagedjs`, la pagination finie ; - **les cibles des numéros** : chaque `:ref` et chaque entrée d'index porte un `href` vers une ancre, que `target-counter(attr(href), page)` transforme en numéro de page. Si PDF3.0 dit **no-go**, le livre sort en P8 avec Chromium seul : page de titre, table des matières en liens sans numéros, notes en fin de chapitre, index sans numéros de page (liens), pas de titres courants par chapitre. Le critère « numéros de table des matières vérifiés » de `06` passe alors à la phase où un moteur les fournit ; c'est une décision à écrire à la fin du spike, pas un repli silencieux. ### 4.3 L'édition web - **`BookReader`** (React, `@recit/book`) : un chapitre par page, précédent et suivant (liens et touches `←` `→` hors champ de saisie), table des matières en tiroir sur mobile, notes en fin de chapitre avec lien retour, figures numérotées, page d'index A–Z, couverture et page de titre. Plain CSS modules compilés (loi de [19 · Style](/19-style)), mode sombre par `light-dark()`, mesure de ligne autour de 66 caractères, `hyphens: auto` avec le `lang` du chapitre. - **Dans un site** (pont book → docs, `08` §0) : `@recit/site-stories` route une story `format: book` vers une page de couverture (`//`) et une route par chapitre (`///`), par `getRoutes`. La table des matières devient la sidebar par `getNavigation`, que l'API de plugins expose déjà. Pagefind indexe chaque chapitre. Lot B4.0 : vérifier que `getNavigation` peut fournir une sidebar limitée au préfixe du livre ; sinon, la sidebar est le sommaire de `BookReader` et la question 7 se pose. - **Hors site** : `recit build book.md` produit la même édition en statique (une page HTML par chapitre, pour le référencement et la lecture sans JS), avec `@recit/book/runtime` pour la navigation, comme `@recit/deck/runtime`. - **`StoryEmbed format="book"`** montre un chapitre (prop `chapter`) dans une page MDX. ### 4.4 L'EPUB 3 `@recit/book/epub` (Node seulement, comme `@recit/motion/node`) : `writeEpub(story, options) → Uint8Array`. - `mimetype` en premier, non compressé ; `META-INF/container.xml` ; `content.opf` (métadonnées `dc:title`, `dc:creator`, `dc:language`, `dc:identifier`, `dc:rights`, `dcterms:modified`, manifeste et `spine`) ; `nav.xhtml` (table des matières et `landmarks`) ; un XHTML par chapitre et par page de pré et de post-texte ; la couverture ; la feuille du thème ; les polices du thème, embarquées seulement si leur licence le permet (les polices de `@recit/theme` sont sous OFL). - Notes en `