Des diagrammes UML dans les articles de ce blog ?

Aujourd’hui un bref article expliquant comment ajouter une nouvelle capacité à notre blog : ça serait sympa de pouvoir faire des diagrammes UML ?

NOTE: c’est un article commencé en 2020 avant la migration vers SvelteKit, mais largement simplifié en 2021. Croyez-moi sur parole . J’avais dû trifouiller le code de MDsveX et le patcher pour qu’il accepte les blocs code de type plantuml. Je constante en 2021 que ce n’est plus nécessaire, j’ai donc raccourci cet article. En fait il ne reste quasi plus rien à dire… Bonne lecture !

Mais, Pourquoi ?

Juste pour l’expérimentation, bien sûr !

Evidemment, sur un blog y’a pas trop d’intérêt pour coller des diagrammes, mais parfois ça peut être utile.

J’aime bien expliquer avec des carrés et des flèches quand j’ai un tableau blanc à portée de main.

UML

Comment ça, UML ça sert à rien ?

Non, je suis pas tout à fait d’accord, ça a ses avantages pour clarifier ses idées, et expliquer visuellement les choses.

Un bon dessin vaut mieux qu’un long discours.

Oui je prends le sens de “design” comme “dessin de conception”.

Par contre générer du code à partir d’UML, la bonne blague.

J’ai vécu ça au début de ma carrière en 2002-2006 et ça ne marche pas.

Donc, pour moi dans UML je ne retiens que les diagrammes de séquence (des traits, des acteurs, des flèches) et les diagrammes de classes (pour visualiser les liens entre objets.)

PlantUML

Donc habituellement, au boulot, je préconise PlantUML parceque OK, je veux vien faire de l’UML, mais pas question d’installer un gros logiciel pour ça : un bout de texte et ça suffit.

Avec PlantUML, on peut rechercher/remplacer, copier-coller, et appliquer des styles de rendu, etc. C’est hyper souple et ça se lit sans avoir besoin de générer un rendu image.

Exemple:

Truc --> bidule : truc appelle bidule

On voit bien qu’il y a une flèche en ”ascii-art”, non ?

Hé bien PlantUML se contente de tracer des carrés et des flèches à partir de ça.

Attends une minute… tu vois cette image ? Justement, ce blog l’a générée à partir du code précédent !

En vrai, voilà ci-dessous le bloc de code Markdown exact avec plantuml en langage, tout ce qui suit (“diagramme simpliste”) sera collé dans l’attribut alt de l’image générée, pour l’accessibilité (a11y) :

```plantuml diagramme simpliste
Truc --> bidule : truc appelle bidule
```

Ajouter des diagrammes PlantUML

Il existe de nombreux plugin, j’ai choisi celui-là : https://github.com/akebifiky/remark-simple-plantuml

Ce plugin transforme un noeud Markdown de type “code” en noeud “image” en construisant une url spéciale.

Contrairement à ce qui est dit sur le README, si comme pour ce blog vous publiez via sveltekit build avec le static adapter (anciennement sapper export), inutile de l’installer en dépendance principale :

npm install --save-dev @akebifiky/remark-simple-plantuml

Pipeline MDsveX avec Remark

MDsveX utilise Remark et Rehype pour sa pipeline de transformation de MarkDown+Svelte vers Svelte classique (avec Script + CSS + HTML).

Remark et Rehype se basent à leur tour sur UNIST, UNIversal Syntax Tree.

Vous m’en direz tant !

Bon, en fait il suffit d’ajouter un plugin Remark dans notre configuration mdsvex.config.js elle-même importée dans svelte.config.js

import plantuml from "@akebifiky/remark-simple-plantuml"
//...

  remarkPlugins: [
    //...
    [plantuml, { baseUrl: "https://www.plantuml.com/plantuml/svg" }],
    //...
  ]

à partir de là, quand MDsveX va transformer les articles Markdown en composants Svelte, il va passer les plugins Remark et Rehype pour modifier les contenus. Donc si on met un bloc de code avec le langage typé plantuml, cela va déclencher notre plugin dédié, qui va faire son boulot de le transformer en une URL qui a son tour nous affichera un “joli” dessin au lieu du texte en ascii.

Voilà.

Tout ceci est visible sur le code du blog sur GitHub (si vous venez du futur, faudra remonter un peu si je migre encore le socle du blog d’ici là ).

Conclusion

Dans cet article on a vu comment ajouter la génération de diagramme de séquence pour briller en comité d’architecture.

Comme UML c’est du sérieux, pas de GIF ou d’images rigolotes. C’est aussi le premier article en français, on sent que je suis plus à l’aise, non ?

Si vous avez des questions sur UML les dessins avec des boites et des flèches, SvelteKit, MDsveX, ou juste pour faire coucou ou dire merci, mes DMs sont ouverts sur Twitter !