Comment intégrer des diagrammes d'architecture en direct dans vos docs, Notion, Confluence et GitHub

Tout diagramme d'architecture qui finit en capture d'écran dans un wiki lance un lent compte à rebours. Le système change, quelqu'un met à jour la source, et la capture du guide d'onboarding, du runbook et du document de conception reste telle quelle. Six mois plus tard, plus personne ne se fie à aucune d'elles.

La solution tient en une phrase : gardez un seul diagramme en direct et faites pointer chaque page vers lui. Ce guide explique comment faire, cas par cas : sites de documentation, Notion, Confluence, README GitHub et outils de chat, ainsi que la marche à suivre quand une page ne peut pas afficher de diagramme en direct. Pour la démarche d'ensemble, lisez Des diagrammes d'architecture qui ne se périment pas.

Trois façons de montrer un diagramme

Utilisez les deux premières dès que possible, et les exports uniquement là où aucun contenu en direct n'est autorisé.

Obtenir le lien et le code d'intégration

Dans Archboard, ouvrez le diagramme et choisissez Partager :

1. Activez Toute personne avec le lien et copiez le lien de partage. Les spectateurs suivent le diagramme en direct, sans compte, et ne peuvent pas le modifier.
2. Sur Pro, activez Intégration et copiez le code d'intégration. Il ressemble à ceci :

<iframe src="https://getarchboard.app/embed/YOUR_EMBED_TOKEN" width="100%" height="480" style="border:0;border-radius:8px;" allowfullscreen loading="lazy" title="Archboard diagram"></iframe>

Vous pouvez renouveler le lien ou le code d'intégration à tout moment, ce qui rend l'ancien inutilisable, ou désactiver le partage, ce qui déconnecte aussitôt les spectateurs.

Un point à connaître avant de mettre un diagramme en direct sur une page publique : les spectateurs voient les modifications au moment où elles se produisent, ainsi que les noms et curseurs des personnes avec droit de modification qui ont le diagramme ouvert dans l'éditeur, et des agents IA qui y travaillent. Les noms des spectateurs eux-mêmes ne sont jamais affichés.

Sites de documentation

HTML simple, Jekyll, MkDocs et la plupart des générateurs de sites statiques. Collez le code d'intégration là où le diagramme doit apparaître ; leur Markdown accepte le HTML brut. Hugo écarte par défaut le HTML brut du Markdown : placez donc l'iframe dans un shortcode ou définissez markup.goldmark.renderer.unsafe = true dans la configuration du site.

Docusaurus et autres sites MDX. MDX attend du JSX : l'attribut style doit donc être un objet, et les attributs s'écrivent en camelCase :

<iframe
  src="https://getarchboard.app/embed/YOUR_EMBED_TOKEN"
  width="100%"
  height="480"
  style={{ border: 0, borderRadius: 8 }}
  allowFullScreen
  loading="lazy"
  title="Checkout service architecture"
/>

Deux petites habitudes aident les lecteurs : choisissez une hauteur qui affiche le diagramme sans défilement, et donnez à chaque iframe un title qui décrit le diagramme ; les lecteurs d'écran l'annoncent.

Notion

Tapez /embed, choisissez Embed et collez l'URL de l'attribut src du code d'intégration (pas toute la balise iframe). Notion charge les contenus intégrés via son propre service d'embed ; si une page ne peut pas s'afficher directement, Notion affiche une erreur à la place. Dans ce cas, collez le lien de partage comme signet : un clic ouvre le diagramme en direct.

Confluence

Confluence Cloud n'accepte ni HTML brut ni code iframe dans l'éditeur. Collez le lien de partage, que Confluence transforme en lien ou en carte. Si votre organisation autorise les apps du Marketplace, une app de macro iframe ou HTML peut afficher l'intégration directement dans la page.

Confluence Data Center propose une macro HTML que les administrateurs peuvent activer. Elle permet à toute personne ayant un droit de modification d'ajouter du HTML et du JavaScript arbitraires aux pages, si bien que de nombreuses organisations la laissent désactivée. Demandez à votre administrateur avant de compter dessus.

README GitHub et Markdown dans les dépôts

GitHub n'affiche pas les iframes dans le Markdown : une intégration en direct est donc impossible dans un README. Le meilleur substitut est un SVG exporté, commité à côté du code et relié au diagramme en direct :

[![Checkout architecture](docs/architecture.svg)](https://getarchboard.app/s/YOUR_SHARE_TOKEN)

Les lecteurs voient l'image dans le README, et un clic ouvre la version actuelle. Ajoutez « export du diagramme mis à jour ? » à votre template de pull request, et commitez aussi l'export JSON si vous voulez relire les changements du diagramme comme des données.

Slack, Teams, Jira et e-mail

Collez le lien de partage. Il ouvre toujours la version actuelle : un vieux message dans un fil ne renvoie donc pas vers une image périmée.

Les pratiques qui font tenir le dispositif

• Un diagramme, plusieurs liens. Ne copiez jamais un diagramme dans un second fichier pour « faire une version pour le wiki ».
• Mettez le titre, le responsable et la date de dernière revue sur le canevas. Les intégrations et les liens montrent le canevas, pas les métadonnées de votre page.
• Partagez délibérément. Un lien ou une intégration sur une page publique rend le diagramme public. Gardez l'architecture interne sur des pages internes, et renouvelez le lien s'il fuite.
• Faites de l'export une solution de repli, pas une habitude. Chaque export est une copie qui peut devenir obsolète.

Voici l'ensemble du dispositif sur un seul canevas :

Le mettre en place dans Archboard

Ouvrez n'importe quel diagramme, choisissez Partager et activez le lien ; sur Pro, activez aussi l'intégration. Si vous commencez un diagramme pour votre documentation, les modèles et les exemples sont un bon point de départ, et le diagramme ci-dessus utilise neuf boîtes du pack Base, dans les limites du plan Free.

FAQ

Puis-je intégrer un diagramme avec le plan Free ? Free inclut le lien de partage avec la marque Archboard. L'intégration iframe fait partie de Pro et d'Enterprise.

Les spectateurs ont-ils besoin d'un compte ? Non. Toute personne qui a le lien, ou qui ouvre la page contenant l'intégration, peut voir le diagramme en direct. Elle ne peut pas le modifier.

Puis-je arrêter le partage plus tard ? Oui. Renouvelez le lien ou le code d'intégration pour invalider l'ancien, ou désactivez le partage pour déconnecter immédiatement les spectateurs.

Un SVG exporté se met-il à jour quand le diagramme change ? Non. Les exports sont des copies. Réexportez quand le diagramme change, ou utilisez un lien ou une intégration partout où c'est possible.

Pourquoi mon intégration affiche-t-elle une erreur dans Notion ou Confluence ? Ces deux outils contrôlent ce qui peut être intégré. Utilisez plutôt le lien de partage comme signet ou comme carte, ou interrogez votre administrateur sur les apps d'intégration.

Commencez gratuitement — un siège, sans carte bancaire.