EPUB - Format de documentation accessible

Vue d'ensemble

EPUB (Electronic Publication) est un format de livre numérique standardisé par l'IDPF (International Digital Publishing Forum), maintenant intégré au W3C. C'est le format privilégié pour produire de la documentation accessible.

Dans le contexte de Codexia, EPUB est utilisé pour :

Exporter la documentation technique du projet
Produire des documents accessibles conformes RGAA AA
Permettre une consultation multi-supports (web, liseuses, applications)

Pourquoi EPUB pour l'accessibilité ?

Avantages intrinsèques

Basé sur HTML et CSS : Technologies web standard, bien maîtrisées
Structuré : Sémantique HTML native (headings, lists, tables)
Reflowable : Contenu adaptable à la taille d'écran (responsive)
Métadonnées riches : Support natif des informations d'accessibilité
Compatible : Lecture sur liseuses, tablettes, smartphones, lecteurs d'écran

Normes d'accessibilité

EPUB Accessibility 1.1 : Spécification du W3C pour l'accessibilité des EPUB
WCAG 2.1 AA : Conformité native si le contenu HTML est accessible
ARIA : Support des attributs ARIA pour enrichir la sémantique
Media Overlays : Synchronisation texte/audio pour les personnes dyslexiques

Structure d'un fichier EPUB

Un fichier EPUB est une archive ZIP contenant :

mon-livre.epub (ZIP)
├── mimetype                  # Type MIME (application/epub+zip)
├── META-INF/
│   └── container.xml         # Point d'entrée
├── OEBPS/                    # Contenu principal
│   ├── content.opf           # Manifest, métadonnées, ordre de lecture
│   ├── toc.ncx               # Table des matières (EPUB 2)
│   ├── nav.xhtml             # Table des matières HTML (EPUB 3)
│   ├── chapter1.xhtml        # Chapitres en XHTML
│   ├── chapter2.xhtml
│   ├── styles/
│   │   └── main.css          # Feuilles de style
│   └── images/
│       └── cover.jpg         # Images

Fichiers clés

`mimetype`

application/epub+zip

`META-INF/container.xml`

<?xml version="1.0" encoding="UTF-8"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
  <rootfiles>
    <rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
  </rootfiles>
</container>

`OEBPS/content.opf`

Manifest complet du livre avec métadonnées d'accessibilité :

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.idpf.org/2007/opf" version="3.0" xml:lang="fr" unique-identifier="uid">
  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
    <dc:title>Codexia - Documentation Technique</dc:title>
    <dc:creator>Mathieu Adrien</dc:creator>
    <dc:language>fr</dc:language>
    <dc:identifier id="uid">telaria-doc-2026</dc:identifier>
    <meta property="dcterms:modified">2026-02-20T10:00:00Z</meta>

    <!-- Métadonnées d'accessibilité -->
    <meta property="schema:accessMode">textual</meta>
    <meta property="schema:accessMode">visual</meta>
    <meta property="schema:accessModeSufficient">textual</meta>
    <meta property="schema:accessibilityFeature">structuralNavigation</meta>
    <meta property="schema:accessibilityFeature">tableOfContents</meta>
    <meta property="schema:accessibilityHazard">none</meta>
    <meta property="schema:accessibilitySummary">
      Cette publication est conforme WCAG 2.1 niveau AA.
    </meta>
  </metadata>

  <manifest>
    <item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>
    <item id="chapter1" href="chapter1.xhtml" media-type="application/xhtml+xml"/>
    <item id="css" href="styles/main.css" media-type="text/css"/>
  </manifest>

  <spine>
    <itemref idref="chapter1"/>
  </spine>
</package>

Bonnes pratiques d'accessibilité

1. Structure sémantique

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="fr" lang="fr">
<head>
  <meta charset="UTF-8"/>
  <title>Introduction</title>
  <link rel="stylesheet" href="styles/main.css"/>
</head>
<body>
  <section epub:type="chapter" role="doc-chapter">
    <h1>Introduction à Codexia</h1>
    <p>Codexia est une application de documentation...</p>

    <section>
      <h2>Objectifs du projet</h2>
      <ul>
        <li>Vitrine technique</li>
        <li>Documentation auto-générée</li>
      </ul>
    </section>
  </section>
</body>
</html>

2. Images accessibles

<!-- Image avec alternative textuelle -->
<figure>
  <img src="images/architecture.png"
       alt="Diagramme de l'architecture Codexia montrant les couches Controller, Service, Repository et Entity"/>
  <figcaption>Architecture en couches de Codexia</figcaption>
</figure>

<!-- Image décorative -->
<img src="images/decoration.png" alt="" role="presentation"/>

3. Tableaux accessibles

<table>
  <caption>Liste des modules Codexia</caption>
  <thead>
    <tr>
      <th scope="col">Module</th>
      <th scope="col">Statut</th>
      <th scope="col">Version</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Core</td>
      <td>Stable</td>
      <td>1.0.0</td>
    </tr>
  </tbody>
</table>

4. Navigation accessible

<!-- nav.xhtml : Table des matières -->
<nav epub:type="toc" role="doc-toc">
  <h1>Table des matières</h1>
  <ol>
    <li><a href="chapter1.xhtml">Introduction</a></li>
    <li>
      <a href="chapter2.xhtml">Architecture</a>
      <ol>
        <li><a href="chapter2.xhtml#backend">Backend</a></li>
        <li><a href="chapter2.xhtml#frontend">Frontend</a></li>
      </ol>
    </li>
  </ol>
</nav>

5. CSS accessible

/* Respecter les préférences utilisateur */
body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  font-size: 1rem;
  line-height: 1.6;
  color: #1a1a1a;
  background-color: #ffffff;
}

/* Contrastes conformes WCAG AA (4.5:1) */
a {
  color: #0066cc;
}

a:hover, a:focus {
  color: #004499;
  text-decoration: underline;
}

/* Support du mode sombre (respecter prefers-color-scheme) */
@media (prefers-color-scheme: dark) {
  body {
    color: #e0e0e0;
    background-color: #1a1a1a;
  }

  a {
    color: #66b3ff;
  }
}

/* Ne pas forcer de taille de police fixe */
/* Permettre le zoom jusqu'à 200% sans perte de contenu */

Outils de production

Générateurs EPUB

Pandoc (recommandé pour Codexia)

pandoc input.md -o output.epub \
  --metadata title="Codexia Documentation" \
  --metadata author="Mathieu Adrien" \
  --metadata lang="fr" \
  --toc --toc-depth=2 \
  --epub-cover-image=cover.jpg

Calibre : Interface graphique, conversion de formats
Sigil : Éditeur EPUB WYSIWYG

Validation

EPUBCheck : Validateur officiel EPUB
```
epubcheck mon-livre.epub
```
Ace by DAISY : Audit d'accessibilité EPUB
```
ace mon-livre.epub
```

Intégration dans Codexia

Workflow de production

Rédaction : Documentation en Markdown (dans /docs)
Génération : Script automatisé (Pandoc) pour convertir en EPUB
Validation : EPUBCheck + Ace
Publication : Mise à disposition du fichier EPUB sur le site

Script de génération

#!/bin/bash
# scripts/generate-epub.sh

DOCS_DIR="docs"
OUTPUT_DIR="public/downloads"
EPUB_FILE="telaria-documentation.epub"

# Concaténer les fichiers Markdown dans l'ordre
cat ${DOCS_DIR}/README.md \
    ${DOCS_DIR}/philosophie.md \
    ${DOCS_DIR}/ingenierie.md \
    > /tmp/codexia-full.md

# Générer l'EPUB
pandoc /tmp/codexia-full.md \
  -o ${OUTPUT_DIR}/${EPUB_FILE} \
  --metadata title="Codexia - Documentation Technique" \
  --metadata author="Mathieu Adrien" \
  --metadata lang="fr" \
  --toc --toc-depth=2 \
  --epub-cover-image=assets/images/cover.jpg \
  --css=assets/styles/epub.css

# Valider
epubcheck ${OUTPUT_DIR}/${EPUB_FILE}
ace ${OUTPUT_DIR}/${EPUB_FILE} -o ${OUTPUT_DIR}/ace-report

echo "EPUB généré : ${OUTPUT_DIR}/${EPUB_FILE}"

Checklist d'accessibilité EPUB

Métadonnées d'accessibilité présentes dans content.opf
Structure sémantique HTML5 correcte (<section>, <article>, <nav>)
Hiérarchie des titres respectée (h1 → h2 → h3, sans saut)
Alternatives textuelles pour toutes les images informatives
Images décoratives marquées alt="" ou role="presentation"
Tableaux avec <caption>, <th scope>, <thead>, <tbody>
Liens explicites (pas de "cliquez ici")
Contrastes conformes WCAG AA (4.5:1 pour texte normal)
Pas de taille de police fixe (utiliser rem, em, %)
Support du zoom jusqu'à 200% sans perte de contenu
Table des matières (nav.xhtml avec epub:type="toc")
Langue du document déclarée (xml:lang, lang)
Validation EPUBCheck sans erreur
Audit Ace sans problème critique

Ressources

Spécifications

Outils

Pandoc - Convertisseur universel de documents
EPUBCheck - Validateur EPUB
Ace by DAISY - Audit d'accessibilité EPUB
Calibre - Gestion et conversion de livres numériques
Sigil - Éditeur EPUB