Documentation web — telaria-doc navigable depuis le site (/docs)

Ré-inclure la documentation telaria-doc dans l'application telaria et la rendre lisible et parcourable depuis le site web, à /docs, avec une navigation en treeview et un rendu Markdown accessible. Statut : livré — viewer /docs en prod (telaria.dev). Voir « État d'implémentation » ci-dessous (écarts vs la conception).

État d'implémentation (2026-06-04)

Livré et en prod (telaria.dev) : le viewer /docs (arborescence + rendu Markdown GFM, coloration syntaxique serveur, navigation AJAX / Turbo Frames, liens inter-docs), avec stripping du cartouche front-matter au rendu (FrontMatterExtension).

Écarts à connaître vs la conception ci-dessous :

• Inclusion du corpus : l'implémentation utilise bin/sync-docs.php (resynchronisation du dossier docs/) + une policy de publication (allowlist app.docs.published_paths, default-deny) côté telaria — et non le git submodule envisagé en §2/§13. Direction co-décidée pour la suite : remplacer l'allowlist par un champ public: dans le cartouche (canon doc, cap A).
• Chat embarqué : le viewer intègre « le chat » (assistant offcanvas, paramètres figés en BO /admin/chat/params), distinct de « l'assistant » (page /assistant). Voir ia-chatbot.md § « Surfaces livrées ».

1. Contexte et objectif

Historiquement, telaria-doc était un bundle dans telaria, puis extrait en dépôt autonome. On souhaite aujourd'hui ré-inclure ce contenu dans l'application et le servir au public à /docs, sans le dupliquer.

Double valeur vitrine :

• La documentation devient un produit consultable (cohérent avec « la documentation est le produit »).
• C'est la même source que l'index RAG/MCP (voir §9) → un seul corpus, plusieurs surfaces.

2. Inclusion du contenu (mécanisme)

Exigences : pas de duplication, contenu versionné, telaria-doc reste son propre dépôt (source de vérité). Le modèle « clone/copie manuelle » est écarté.

Options :

Décision (avec l'instance codexia) : git submodule monté à docs/ (racine, hors public/, servi par un contrôleur), pinné sur un commit figé de telaria-doc. Publier une mise à jour de doc = bumper le pointeur du submodule → corpus reproductible (cohérent avec « l'index RAG est un artefact dérivé reconstructible »). Déploiement/CI : git submodule update --init --recursive. Remplace l'ancien script de clone (bin/sync-docs.php).

3. Rendu Markdown

Conforme au profil CDX-MD (voir markdown.md) :

• CommonMark + GFM (tables, task lists, autolinks, code clôturé).
• HTML brut filtré (whitelist) à la sortie.
• Pipeline : pré-traitement des directives Codexia → parsing → génération HTML → post-traitement accessibilité → sanitization.

Rendu accessible (obligatoire, RGAA AA) : hiérarchie de titres cohérente, alt sur les images, tableaux avec <thead>/<th scope>, liens explicites, <pre><code class="language-…"> pour le code.

4. Navigation (treeview)

• Un arbre de la structure documentaire (dossiers/fichiers), construit depuis l'arborescence du dépôt et/ou la toc.md.
• Repli/déploiement des branches ; item actif marqué aria-current="page".
• Accessible : navigable au clavier, structure sémantique (liste imbriquée ou pattern ARIA tree), focus visible.

5. Routes

• GET /docs → accueil (rendu du README.md ou de la toc.md).
• GET /docs/{path} → rendu d'un document (path = chemin relatif dans le dépôt doc).
• 404 propres pour un chemin inexistant ou hors périmètre.

6. Périmètre et exclusions

• Exclure SCRATCH.md et inputs/legacy/ (respect de .aiignore) — jamais servis.
• Ne servir que des fichiers sous la racine documentaire (cf. sécurité §10).
• Servir le Markdown et ses ressources (SVG d'aperçu, HTML de thème) ; pas de fichiers techniques (.git, etc.).

7. Accès

Le site est une vitrine → /docs est public en lecture (décidé). inputs/legacy/ et SCRATCH.md exclus avant tout rendu.

8. Accessibilité et design

• RGAA 4.1 AA sur les pages /docs et le treeview.
• Intégration au design system (Codexia\UiBundle, specs/design.md, specs/ui.md).
• Amélioration progressive : la navigation fonctionne sans JavaScript (liens serveur) ; le repli/déploiement JS est un confort.

9. Synergie avec l'initiative IA

telaria-doc devient une source unique à trois usages :

• Navigation humaine (/docs, cette spec) ;
• Recherche/Q-R IA (chatbot RAG, specs/ia-chatbot.md) ;
• Outils agent (serveur MCP, specs/ia-mcp.md).

Le cœur RAG (specs/ia-coeur.md) indexe le même contenu. Les citations du chatbot peuvent pointer vers les pages /docs correspondantes → boucle vertueuse.

10. Sécurité

• Path traversal : normaliser et vérifier que le chemin résolu reste sous la racine documentaire ; refuser tout .. ou chemin absolu.
• Sanitization HTML stricte (whitelist) à la sortie du rendu Markdown.
• Exclusions (SCRATCH.md, inputs/legacy/) appliquées avant tout rendu.

11. Tests (cas concrets)

• GET /docs rend l'accueil (toc/README) en HTML accessible.
• GET /docs/{path} d'un document valide → HTML correct (titres, liens, tableaux th scope).
• Chemin hors racine (../, absolu) → refus / 404 (anti path traversal).
• SCRATCH.md et un fichier de inputs/legacy/ → jamais servis (404).
• Le treeview marque l'item actif (aria-current) et est navigable au clavier.
• Sortie HTML sanitizée (balises non autorisées retirées).

12. Production documentaire d'accompagnement (doctrine)

13. Décisions (tranchées avec l'instance codexia)

1. Inclusion : git submodule (remplace le clone). Pinné sur un commit figé → corpus reproductible.
2. Emplacement : docs/ à la racine de telaria, hors public/, servi par un contrôleur (exclu du webroot).
3. Accès : public en lecture ; inputs/legacy/ + SCRATCH.md exclus avant rendu.
4. Rendu : à la volée + cache HTTP (ETag / Last-Modified) en premier ; pré-rendu/cache si besoin de perf.
5. Treeview : dérivé de l'arborescence réelle (toujours exacte), enrichi par toc.md (ordre/libellés) si utile.

Restes fins à caler à l'implémentation : invalidation du cache au bump du submodule ; gabarit exact du treeview.

Documents liés

• Profil Markdown : markdown.md
• Conventions de structure : DOCUMENTATION.md
• Source partagée (RAG) : specs/ia-coeur.md
• Chatbot (citations vers /docs) : specs/ia-chatbot.md
• Accessibilité UI : accessibility/interface-utilisateur.md

Implémentation

Historique des décisions