Maintenance script : Documentation détaillée du déploiement Mermaid, PlantUML et BPMN JS

2026-03-18T22:00:57Z

Documentation détaillée du déploiement Mermaid, PlantUML et BPMN JS

Nouvelle page

= 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é :

<syntaxhighlight lang="php">
$wgRawHtml = true;
</syntaxhighlight>

Cela permet d'utiliser des blocs HTML comme <code><div></code> et <code><pre class="..."></code> 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 :

<syntaxhighlight lang="html">
<pre class="oc-mermaid">
...
</pre>
</syntaxhighlight>

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 :

<syntaxhighlight lang="javascript">
https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js
</syntaxhighlight>

=== 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 :

<syntaxhighlight lang="html">
<pre class="oc-plantuml">
...
</pre>
</syntaxhighlight>

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

=== Chargement ===
Le navigateur charge :
* un encodeur JS :
<syntaxhighlight lang="javascript">
https://cdn.jsdelivr.net/npm/plantuml-encoder/dist/plantuml-encoder.min.js
</syntaxhighlight>
* puis utilise un backend de rendu SVG :
<syntaxhighlight lang="text">
https://kroki.io/plantuml/svg/
</syntaxhighlight>

=== 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 :

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

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

=== Chargement ===
Le viewer est chargé depuis :

<syntaxhighlight lang="javascript">
https://cdn.jsdelivr.net/npm/bpmn-js@18/dist/bpmn-navigated-viewer.production.min.js
</syntaxhighlight>

=== 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 ==
* [[Exemple Mermaid]]
* [[Exemple PlantUML]]
* [[Exemple BPMN JS]]

== 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 <code>$wgRawHtml</code>.

Déploiement Mermaid PlantUML BPMN JS - Historique des versions

Maintenance script : Documentation détaillée du déploiement Mermaid, PlantUML et BPMN JS

Maintenance script : Documentation détaillée du déploiement Mermaid, PlantUML et BPMN JS