Déploiement de Mermaid, PlantUML et BPMN JS dans MediaWiki

Cette page documente le déploiement réalisé sur ce wiki pour permettre le rendu de schémas Mermaid, PlantUML et BPMN JS.

Objectif

L'objectif est de pouvoir écrire des schémas directement dans des pages MediaWiki, puis les rendre côté navigateur sans devoir téléverser une image statique à chaque modification.

Vue d'ensemble

Le déploiement repose sur quatre éléments :

une configuration MediaWiki autorisant les blocs HTML nécessaires
un script global chargé via MediaWiki:Common.js
une feuille de style globale via MediaWiki:Common.css
des conventions de balisage par type de diagramme

Modifications MediaWiki

LocalSettings.php

Le paramètre suivant a été activé :

$wgRawHtml = true;

Cela permet d'utiliser des blocs HTML comme <div> et <pre class="..."> dans les pages du wiki.

Conséquence sécurité

Cette option simplifie beaucoup l'intégration, mais elle est plus permissive. Dans ce wiki, cela reste acceptable car l'édition anonyme est désactivée. Pour un environnement plus ouvert, il faudrait préférer :

une extension dédiée
ou des balises parser custom
ou un filtrage beaucoup plus strict

Déploiement de Mermaid

Principe

Mermaid est chargé côté navigateur depuis un CDN, puis le script global cherche les blocs :

<pre class="oc-mermaid">
...
</pre>

Le contenu texte est ensuite rendu en SVG dans la page.

Chargement

Le chargement est fait depuis MediaWiki:Common.js avec une URL de type :

https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js

Avantages

édition facile en texte
nombreux types de schémas
très pratique pour la documentation technique et fonctionnelle

Limites

dépend d'un CDN
certains schémas complexes demandent une syntaxe stricte
ce n'est pas du BPMN strict

Déploiement de PlantUML

Principe

PlantUML est aussi écrit directement dans le wiki, dans un bloc :

<pre class="oc-plantuml">
...
</pre>

Le texte est encodé côté client, puis envoyé à un service de rendu SVG compatible PlantUML.

Chargement

Le navigateur charge :

un encodeur JS :

https://cdn.jsdelivr.net/npm/plantuml-encoder/dist/plantuml-encoder.min.js

puis utilise un backend de rendu SVG :

https://kroki.io/plantuml/svg/

Avantages

très riche pour diagrammes UML, séquence, activité, architecture
versionnable en texte
pratique pour la documentation technique

Limites

dépend actuellement d'un service de rendu externe
moins approprié que BPMN JS pour du BPMN natif

Déploiement de BPMN JS

Principe

BPMN JS permet d'afficher un vrai diagramme BPMN à partir d'un XML BPMN intégré dans la page.

Structure utilisée :

<div class="oc-bpmn-container">
  <div class="oc-bpmn-viewer"></div>
  <pre class="oc-bpmn-xml">... XML BPMN ...</pre>
</div>

Le bloc XML est masqué après chargement et rendu dans la zone oc-bpmn-viewer.

Chargement

Le viewer est chargé depuis :

https://cdn.jsdelivr.net/npm/bpmn-js@18/dist/bpmn-navigated-viewer.production.min.js

Avantages

rendu BPMN natif
zoom et navigation
adapté aux workflows métier sérieux

Limites

nécessite du XML BPMN correct
plus verbeux à écrire à la main
dépend actuellement d'un CDN

Rôle de MediaWiki:Common.js

Le script global fait plusieurs choses :

charge les bibliothèques JS externes
détecte les blocs Mermaid / PlantUML / BPMN
transforme ces blocs en rendus visuels
affiche un message d'erreur si le rendu échoue

Rôle de MediaWiki:Common.css

La feuille de style ajoute :

une présentation homogène des diagrammes
des bordures et marges lisibles
une zone dédiée pour le viewer BPMN
un style pour les messages d'erreur

Dépendances externes actuelles

Le déploiement actuel dépend de ressources externes :

Mermaid via jsDelivr
plantuml-encoder via jsDelivr
BPMN JS via jsDelivr
rendu PlantUML via Kroki

Évolutions possibles

Pour rendre la solution plus autonome, on pourrait :

héberger localement les assets JS
déployer un service Kroki local
remplacer l'usage de raw HTML par une vraie extension MediaWiki
ajouter des templates wiki pour standardiser les schémas

Cas d'usage recommandés

Mermaid : flowcharts, séquences simples, ERD, états, gantt, gitgraph
PlantUML : UML, séquence, composants, activités, architecture
BPMN JS : processus métier BPMN structurés

Pages d'exemple existantes

Conclusion

Le déploiement actuel offre une solution souple et rapide pour documenter des workflows et des architectures directement dans le wiki. Il privilégie la facilité de mise en place, avec un compromis assumé : dépendances externes et usage de $wgRawHtml.