DWA Slides pour VS Code

Rédigez des présentations Marp avec le langage DWA Core v1 : complétion des classes, diagnostics de structure, débordements mesurés dans le vrai rendu, export PowerPoint éditable et thèmes d’organisation.

Documentation complète : https://marp.yassine-hadi.net/fr/extension/

Installation rapide

1. Installer DWA Slides depuis les extensions de VS Code. Marp for VS Code s’installe avec elle, pour l’aperçu.
2. Au premier lancement, accepter l’installation du CLI dwa (téléchargé depuis marp.yassine-hadi.net, signature vérifiée) : il fait fonctionner l’extension.
3. Ouvrir un fichier Markdown, puis exécuter DWA : gérer les thèmes. Sélectionner un CSS (par exemple le thème de référence). Un CSS du projet est utilisé tel quel ; un CSS venant d’ailleurs est validé puis importé dans themes/ du projet. Le document reçoit theme: Nom ; aucun réglage n’est modifié.
4. Utiliser le frontmatter suivant :

---
marp: true
theme: DWA
paginate: true
---

<!-- _class: content cols-2 with-title cards -->

# Deux approches

> ## Première approche
>
> Une courte explication.

<!-- -->

> ## Seconde approche
>
> Un autre point de vue.

Aucun compte ni service d’IA n’est requis. Node.js et npm ne sont nécessaires que pour développer ou reconstruire l’extension, pas pour l’utiliser.

Pendant l’écriture

• Nouvelle slide : taper --- après une ligne vide. Si la nouvelle slide est vide, une suggestion en texte fantôme propose <!-- _class: -->, immédiatement après le séparateur ou sur la ligne vide suivante. Tab l’insère et place le curseur après _class: , puis ouvre le choix du layout. Échap masque la suggestion. Le YAML, les blocs de code et les slides déjà remplies ne déclenchent pas cette proposition. Cette fonction utilise les suggestions inline de VS Code (editor.inlineSuggest.enabled).
• Suggestions : dans <!-- _class: … -->, saisir une classe ou utiliser Ctrl+Espace. La documentation décrit sa structure et donne un exemple. Le premier choix est un layout : content, title, chapter, callout, cover, toc ou closing. cover est un raccourci du menu qui insère title, le nom effectivement reconnu par ce CSS. Après validation, un espace est ajouté et le menu suivant s’ouvre : compositions pour content, puis options adaptées à la composition, palettes et tailles. fit/bg sont proposés pour les compositions avec image, cols-N pour les colonnes, galeries et timelines compatibles. Les classes déjà présentes et les combinaisons incompatibles sont filtrées.
• Survol : explication d’une classe sous le pointeur.
• Problèmes : classes inconnues, combinaisons ambiguës, titres/légendes manquants, mauvaise structure des images, groupes, tableaux ou listes.
• Ampoule / Ctrl+. : appliquer une correction proposée. Le contenu n’est restructuré qu’après ce choix. cols-3 autorise plusieurs rangées.
• Sans commentaires d’exemple : les modèles sont insérés directement en Markdown. Les anciens blocs marqués dwa-example sont retirés à l’ouverture ou à la sélection d’un document DWA, sans toucher aux autres commentaires.
• Structure préremplie : si la slide est vide, le layout choisi insère le Markdown de départ : titre/sous-titre/auteur pour title, numéro et titre pour chapter, liste pour toc, trois groupes pour cols-3, etc. Le texte déjà présent n’est jamais remplacé. content seul attend une composition ou with-title avant de préremplir la slide. Les chemins d’images proposés sont des emplacements à compléter avec vos fichiers.
• Problèmes → corrections rapides → DWA : copier le layout à remplir : copie dans le presse-papiers la directive et le modèle complet de la slide concernée. L’action est disponible pour les diagnostics de structure et les débordements, même si aucune correction automatique ne suffit.

Les seuls commentaires générés sont les directives Marp et les séparateurs vides nécessaires entre groupes. Aucun bloc explicatif dwa-example n’est ajouté.

Les suggestions Marp avec l’icône clé à molette sont de type Property. VS Code ne permet pas à une extension de supprimer individuellement les suggestions d’une autre extension. À l’ouverture d’un document DWA, l’extension configure donc [markdown].editor.suggest.showProperties: false dans les paramètres du dossier de travail, en conservant les autres réglages. Ce filtre concerne les suggestions Property de tous les Markdown de ce dossier. Les directives Marp (theme, paginate, header, backgroundColor…) sont reproposées par DWA dans le frontmatter uniquement. Les valeurs proposées par Marp restent disponibles. Ouvrir un dossier dans VS Code pour appliquer ce filtre. Pour rétablir les suggestions Property : désactiver dwa.cleanSuggestions, puis remettre editor.suggest.showProperties à true dans [markdown].

La directive persistante class est comprise pour les diagnostics et les suggestions ; la génération automatique se déclenche sur _class. Les exemples dans les blocs de code et les commentaires ordinaires ne sont pas interprétés comme des directives. Les fichiers Windows CRLF sont pris en charge.

Mesure des débordements

Le rendu est effectué dans un processus séparé, avec Marp Core, le CSS choisi, les images et les polices locales. Il mesure la zone utile de chaque slide et les fragments de texte dépassant leur colonne, carte ou cellule. Le recadrage volontaire d’une image image-full bg n’est pas signalé comme une erreur. Les retours apparaissent dans Problèmes, avec la source DWA rendu. L’ampoule permet d’essayer medium ou small.

Un navigateur Chrome, Chromium ou Edge doit être installé dans l’environnement qui exécute l’extension. En WSL ou SSH, il faut un navigateur dans cet environnement. Si la détection échoue, renseigner dwa.overflow.browserPath. Aucun navigateur n’est téléchargé automatiquement par l’extension.

Le contrôle se lance après une pause, ou avec un clic sur la barre d’état. La barre d’état indique la mesure en cours, les débordements, une mesure partielle ou un navigateur indisponible. Les détails sont dans Sortie → DWA Slides.

Limites explicites :

• Les documents doivent être enregistrés pour résoudre les chemins d’images.
• Les ressources distantes ne sont pas téléchargées. Les images manquantes ou distantes entraînent une indication de mesure partielle.
• Les polices installées influencent le résultat ; Montserrat absente utilise le remplacement défini par le thème.
• Le HTML libre est désactivé pour le rendu de contrôle. Les extensions Marp tierces et le CSS/HTML arbitraire du document ne constituent pas le contrat DWA.
• Les superpositions entre éléments qui restent dans leur cadre ne sont pas toutes détectées ; les règles de structure complètent la mesure géométrique.
• Le contrôle visuel est désactivé dans les espaces de travail non approuvés.
• Si le diagnostic expérimental markdown.marp.diagnostics.slideContentOverflow de Marp est aussi activé, désactiver l’un des deux contrôles pour éviter des avertissements semblables. DWA ne modifie pas ce réglage automatiquement.

Paramètres

Développement et validation

Depuis ce dossier, avec Node.js 22 ou plus récent :

npm ci
npm run check
npm test
npm run package

Le VSIX est créé dans dist/, ignoré par Git. Il contient le serveur, le client et le moteur de rendu compilés ; le CSS reste le fichier choisi dans le projet.

Les tests de rendu utilisent un navigateur installé. Pour en choisir un :

DWA_TEST_BROWSER=/chemin/vers/chrome npm test

Ouvrir ce dossier dans VS Code et appuyer sur F5 pour lancer une fenêtre de développement. Test automatisé dans une vraie fenêtre VS Code :

npm run test:vscode
# Linux sans affichage :
xvfb-run -a npm run test:vscode

Ce dernier test télécharge une distribution de test de VS Code dans le dossier temporaire système, et utilise un profil isolé.

Organisation :

L’extension est une fine couche VS Code. Toute la logique DWA est dans le serveur de langage dwa lsp du CLI Rust (apps/cli-rs/src/lsp/) : analyse et diagnostics, complétion, survol, corrections, structures préremplies, mesure des débordements et des callouts dans Chromium, export PowerPoint, thèmes d’organisation et serveur local qui les sert à Marp. L’extension utilise le dwa installé sur le poste, le même que pour le terminal et les agents de code : réglage dwa.cliPath, sinon le PATH, sinon le dossier de l’installateur (~/.local/bin, %LOCALAPPDATA%\dwa\bin). S’il manque, elle propose de l’installer depuis le site (empreinte SHA-256 vérifiée) ; s’il est trop ancien (minimum dans src/cli.ts), de le mettre à jour par dwa self update. Commande : DWA : installer ou mettre à jour le CLI dwa. Sur un poste distant (WSL, SSH), le CLI est installé côté distant.

• src/extension.ts : client LSP, commandes, barre d’état, suggestion de nouvelle slide.
• src/hub.ts : dialogues des thèmes d’organisation (connexion, choix, état).
• src/protocol.ts : méthodes dwa/* échangées avec le serveur.
• src/cli.ts : recherche, installation et mise à jour du CLI.

Développement : npm run server construit le CLI Rust de ce poste ; DWA_CLI_BIN=../cli-rs/target/release/dwa le fait utiliser par l’extension (F5). Paquet : npm run package (VSIX d’environ 140 Ko, identique pour tous les systèmes).

Parcours : npm run e2e:authoring (vrai VS Code, dont l’installation du CLI depuis un site local) et npm run e2e:lsp (parité du serveur avec le moteur TypeScript de référence, thèmes servis à Marp, installation et mise à jour du CLI).

Historique des versions : CHANGELOG.md.

Export PowerPoint éditable — 0.9.0

Ouvrir une présentation Marp, puis lancer DWA : exporter un PowerPoint éditable (.pptx) dans la palette de commandes. Choisir le fichier de destination. L’export prend le contenu actuel de l’éditeur, même avant enregistrement, et nécessite un dossier de confiance. Il fonctionne avec tout thème qui respecte le contrat Core v1, du portail ou local.

La présentation est rendue par Marp avec le CSS du thème dans Chromium (dwa.overflow.browserPath). Chaque texte, image et tableau est mesuré puis recréé en objet PowerPoint modifiable, à la même position, avec la police, la taille, la couleur et l’interligne calculés. Le décor du thème (fonds, cartes, puces, numéros, pagination) est capturé sans le contenu et devient le fond de la slide. Les polices incorporées dans le thème sont intégrées au fichier (EOT dans ppt/fonts/), sous leur nom de famille CSS. Les commentaires deviennent les notes de l’orateur.

Fidélité, comparée pixel par pixel dans Microsoft PowerPoint sur toutes les compositions : positions, couleurs, images et décor identiques ; texte à 0–2 px (l’écart d’interligne exact de PowerPoint est compensé avec les mesures de la police).

Sans navigateur, l’export bascule sur la version estimée (géométrie et palettes du Core DWA, sans polices), signalée dans le rapport. Le canal DWA Slides reçoit le rapport : polices absentes ou non intégrables, images absentes ou non prises en charge (WebP/AVIF restent dans le fond), textes à effet conservés en image.

Code : apps/cli-rs/src/pptx.rs (export natif du CLI, appelé par dwa lsp) ; moteur TypeScript de référence dans packages/slides/src/export/, parcours packages/slides/tests/pptx-theme.test.ts.

Proposition d’agent sobre en tokens

Un seul agent rédacteur suffit. Il choisit les classes et le contenu ; le parseur, le validateur et l’exporteur calculent la structure et les positions sans appel à un modèle. packages/slides/src/export/pptx.ts et le CLI dwa exposent déjà ce moteur, sans VS Code, pour un serveur MCP.

Le MCP serait une petite façade locale, proposée, pas implémentée :

La version attendue évite d’écraser une édition faite entre lecture et écriture. Les chemins doivent rester dans le projet autorisé. Le catalogue serait une ressource versionnée, consultée seulement si nécessaire. Les outils renverraient des résultats structurés courts et des liens vers les fichiers ; ni PPTX, ni images en base64, ni CSS embarqué dans le contexte du modèle. Une capture de slide ne serait demandée qu’en cas de besoin visuel. Aucune estimation chiffrée de gain n’est annoncée sans mesure sur des tâches réelles.

Références : PptxGenJS, contrat des outils MCP.

Activation et dépannage — 0.5.2

Le langage des layouts est indépendant du thème graphique. Tous les noms de thèmes sont acceptés : theme: Client-A, theme: Formation, etc. L’assistance s’active avec marp: true, même sans thème explicite (thème Marp par défaut). Un thème déclaré seul active aussi l’assistance pendant la rédaction ; ajouter marp: true pour activer la prévisualisation Marp. YAML et commentaires globaux Marp sont reconnus, ainsi que BOM UTF-8, CRLF et lignes vides initiales. Les thèmes doivent implémenter la syntaxe Core pour que le rendu corresponde aux suggestions ; le nom ne sert pas à reconnaître cette syntaxe.

DWA : préparer ce document pour DWA affiche la cause précise : mode autre que Markdown, dwa.enabled: false, marp: false, YAML invalide/non fermé ou absence de déclaration Marp/thème. Les exemples de code n’activent pas l’assistance. Les URI Markdown virtuelles sont également reconnues ; leur modification et leur rendu local dépendent du fournisseur du document.

DWA : préparer ce document pour DWA passe le document en Markdown et ajoute marp: true, sans imposer ou remplacer son thème. Le contenu et les autres clés YAML sont conservés. Un YAML invalide ou une désactivation contradictoire en commentaire est signalé. Cette commande ne modifie pas dwa.enabled.

Le CSS est choisi d’après le nom déclaré dans le document (theme: Nom), comparé au @theme de chaque CSS, en deux portées :

1. projet : CSS à côté du document, dans themes/ (ou theme/) à la racine du projet, ou déclarés à Marp dans .vscode/settings.json (compatibilité) ;
2. bibliothèque (dossier commun au CLI, à VS Code et aux agents) : thèmes importés et thèmes d’organisation.

Le projet l’emporte. DWA : gérer les thèmes ouvre une page qui liste les thèmes du poste, sans dépendre d’un document : dossiers de l’espace de travail, organisations (installés ou à installer) et thèmes personnels. Elle importe un CSS, ouvre, met à jour ou retire un thème, et l’applique à la présentation ouverte s’il y en a une ; mêmes opérations que dwa theme list | add | remove. Un thème n’est utilisé que s’il est conforme (un brouillon, erreurs de contrat seulement, à la demande ; un thème non sûr jamais). Tous les thèmes utilisables sont servis à Marp par le serveur local. Le moteur de débordement utilise ce CSS. Le PPTX suit le CSS choisi (export mesuré) ; seul l’export estimé, sans navigateur, garde les palettes et dimensions du Core DWA.

Si les commandes sont absentes, vérifier que l’extension est installée/activée dans la fenêtre, le profil et l’environnement WSL/SSH utilisés. Un CSS ou un navigateur manquant affecte le rendu, pas les suggestions du langage.

Transitions expérimentales — 0.6.0

Option désactivée par défaut, à activer dans les paramètres du dossier :

"dwa.experimental.layoutTransitions": true

Sur une slide content, retirer with-title place son unique titre principal hors des groupes dans un commentaire dwa-reserve:title. Retirer with-legend réserve le dernier paragraphe non image s’il termine le contenu de la slide. Remettre l’option restaure le texte réservé. Le commentaire reste dans le fichier mais ne s’affiche pas dans Marp ou le PPTX. Les caractères HTML sont échappés dans la réserve pour conserver aussi les textes contenant des commentaires.

Sans réserve, un titre/légende existant est conservé ; sinon un emplacement à compléter est ajouté. Un dernier paragraphe existant devient la légende selon la convention du layout. Une réserve de titre n’est pas restaurée si un nouveau titre existe déjà. Plusieurs titres principaux ou réserves du même rôle rendent l’opération ambiguë : le contenu reste intact.

Le changement s’applique après 900 ms, sur une directive locale _class valide, si le contenu n’a pas changé entre-temps. Annuler/rétablir ne relance pas les transformations. Désactiver l’option laisse les réserves existantes en place ; elles restent récupérables manuellement dans le Markdown. Cette option est indépendante de dwa.autoScaffold, qui concerne les slides vides.

Cette première expérience ne convertit pas les compositions, ne supprime pas de colonne/image, ne transforme pas les layouts title/chapter et ne modifie pas les slides lors de leur simple ouverture. Les changements graphiques restent gérés par le CSS. Un ajout ou retrait simultané de slides/contenu n’est pas transformé.

Thèmes d’organisation — 0.8.0

Les thèmes publiés sur le portail s’installent une fois pour tout VS Code : toute présentation, quel que soit son dossier (ou hors de tout dossier), peut les utiliser avec theme: Nom.

• DWA : gérer les thèmes, bouton Se connecter au portail — saisir l’adresse (proposée par dwa.hub.portal), le navigateur s’ouvre, comparer le code puis autoriser. Le jeton est chiffré par VS Code (stockage secret du système) et réutilisé ; le portail n’en garde que l’empreinte. Plusieurs portails sont possibles.
• DWA : gérer les thèmes — liste les thèmes de toutes vos organisations ; installe la version choisie (empreinte SHA-256 et contrat vérifiés) et l’écrit dans le frontmatter de la présentation ouverte.
• Vérification discrète — à l’ouverture d’une présentation (au plus une fois par heure et par thème), l’empreinte installée est comparée à celle de la dernière version publiée. Si elle diffère : notification avec Mettre à jour ou Ne plus afficher. Versions retirées et thèmes supprimés sont signalés, avec la version ou le thème de remplacement. dwa.themes.updateNotifications: "silent" coupe toutes les notifications ; l’état reste dans la barre d’état.
• Barre d’état — thème et version de la présentation, erreurs Core v1, mise à jour disponible ; un clic ouvre les actions (mettre à jour, vérifier, contrôler, ouvrir le portail).
• Vérifier les mises à jour, dans le menu du thème de la barre d’état, — vérifie tous les thèmes installés.
• Le bouton Se déconnecter du portail de la page des thèmes — révoque la session ; les thèmes installés restent utilisables hors ligne.

Comment Marp trouve les thèmes

Marp for VS Code n’accepte que des URL ou des chemins internes au dossier ouvert (les chemins absolus sont refusés par ses mainteneurs pour des raisons de sécurité). L’extension garde donc les thèmes dans son stockage global, les sert sur http://127.0.0.1:<port>/dwa-themes/… (seuls les accès à 127.0.0.1 sont acceptés) et déclare ces URL dans les réglages utilisateur markdown.marp.themes, en conservant vos autres entrées. Si un projet déclare ses propres thèmes Marp (ce qui masque la liste utilisateur), les URL y sont ajoutées. Plusieurs fenêtres VS Code partagent le même serveur. Les fonctions DWA (débordements, callouts, PPTX) lisent directement le fichier installé.

Contrôle des thèmes (Core v1)

Tout thème utilisé, du portail ou local, passe par le même validateur que le portail (packages/core) : résultats dans Problèmes sur le fichier CSS, et dans la barre d’état. Contrôler le thème (Core v1), dans le menu du thème de la barre d’état, relance le contrôle ; un CSS déclarant @dwa-language est recontrôlé à chaque enregistrement.

Layout callout (0.7.4)

callout est un layout principal pour un seul titre # centré sur toute la largeur, sur une ou plusieurs lignes. Il reprend les fonds de title, avec color-1 à color-9. Le CSS ne réduit pas automatiquement un texte trop haut : le contrôle de débordement le signale. Suggestions, préremplissage, diagnostics et export PPTX reconnaissent ce layout. Le thème personnalisé doit définir .callout pour obtenir le même rendu Marp.

Le titre callout utilise 3.6em (108 px par défaut), avec une hauteur de ligne de 1,05.

Taille automatique des callouts (0.7.6)

dwa.callout.autoFit est activé par défaut. Après une pause de frappe (dwa.overflow.delay, 1,4 seconde par défaut), le navigateur local choisit la plus grande taille qui tient : 50 à 180 px, par pas de 5 px, soit 27 tailles.

<!-- _class: callout callout-size-105 -->

# Une idée à retenir

Le thème fournit les classes callout-size-50, callout-size-55, …, callout-size-180. L’extension modifie uniquement la classe dans le Markdown : aucune écriture CSS, aucun identifiant par slide, aucun fichier généré. callout conserve le centrage, le retour à la ligne et les fonds de title. Le thème Core garde 24 px de marge intérieure ; sans classe de taille, le titre utilise 108 px. Les thèmes d’organisation peuvent rester immuables.

• Un seul h1 est attendu ; les titres SVG/images gardent leur propre mécanisme.
• Les anciennes classes par slide sont remplacées au prochain calcul réussi. Les anciens blocs CSS gérés dans le Markdown sont alors retirés ; les styles manuels et les exemples de code sont conservés. Les anciennes sections dans un thème personnalisé ne sont pas effacées : elles peuvent encore servir à d’autres fichiers.
• Copier, déplacer ou renommer une présentation conserve les tailles lisibles.
• Pour choisir une taille manuellement, désactiver dwa.callout.autoFit ; les tailles sont proposées dans l’autocomplétion après callout.
• Le thème doit fournir les 27 classes ; sinon un message demande sa mise à jour.
• Un CSS non enregistré suspend la mesure jusqu’à son enregistrement. Une mesure ancienne est ignorée si le texte ou le thème a changé entre-temps.
• Si 50 px ne suffisent pas, le diagnostic de débordement reste disponible.

Le calcul nécessite un fichier enregistré, un espace de travail approuvé et un navigateur local. Il fonctionne même si les diagnostics de débordement sont désactivés. Enregistrer le Markdown pour conserver la taille calculée. Le PDF et la preview utilisent les mêmes classes ; le PPTX utilise la taille en pixels convertie en points. Les métriques PowerPoint peuvent différer du navigateur. Partager le Markdown et le thème CSS, enregistré dans markdown.marp.themes.

Validation : tests Chromium, stabilité du Markdown et du CSS, migration, export PPTX et intégration VS Code avec Marp. npm run test:vscode charge l’extension Marp installée (~/.vscode-server/extensions ou ~/.vscode/extensions), ou celle désignée par DWA_TEST_MARP_PATH.