Cómo insertar diagramas de arquitectura en vivo en tu documentación, Notion, Confluence y GitHub

Todo diagrama de arquitectura que acaba como captura de pantalla en una wiki inicia una lenta cuenta regresiva. El sistema cambia, alguien actualiza el original y la captura de la guía de onboarding, del runbook y del documento de diseño se queda como estaba. Seis meses después, nadie se fía de ninguna.

La solución es fácil de enunciar: mantén un único diagrama en vivo y haz que todas las páginas apunten a él. Esta guía explica cómo hacerlo, caso por caso: sitios de documentación, Notion, Confluence, README de GitHub y herramientas de chat, además de qué hacer donde una página no puede mostrar un diagrama en vivo. Para el flujo de trabajo completo, consulta Diagramas de arquitectura que no se quedan obsoletos.

Tres formas de mostrar un diagrama

Usa las dos primeras siempre que puedas, y las exportaciones solo donde no se permita nada en vivo.

Consigue el enlace y el código de inserción

En Archboard, abre el diagrama y elige Compartir:

1. Activa Cualquiera con el enlace y copia el enlace para compartir. Los espectadores ven el diagrama en vivo, sin cuenta, y no pueden editarlo.
2. En Pro, activa Embeber y copia el código de inserción. Tiene este aspecto:

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

Puedes renovar el enlace o el código de inserción en cualquier momento, con lo que el anterior deja de funcionar, o desactivar el uso compartido, lo que desconecta a los espectadores al instante.

Algo que debes saber antes de poner un diagrama en vivo en una página pública: los espectadores ven los cambios a medida que se hacen, junto con los nombres y cursores de las personas con permiso de edición que tienen el diagrama abierto en el editor y de los agentes de IA que trabajan en él. Los nombres de los propios espectadores nunca se muestran.

Sitios de documentación

HTML puro, Jekyll, MkDocs y la mayoría de los generadores de sitios estáticos. Pega el código de inserción donde deba aparecer el diagrama; su Markdown acepta HTML en bruto. Hugo omite por defecto el HTML en bruto del Markdown, así que coloca el iframe en un shortcode o define markup.goldmark.renderer.unsafe = true en la configuración del sitio.

Docusaurus y otros sitios MDX. MDX espera JSX, así que el atributo style debe ser un objeto y los atributos se escriben 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"
/>

Dos pequeños hábitos ayudan a los lectores: usa una altura en la que el diagrama quepa sin desplazarse y dale a cada iframe un title que describa el diagrama; los lectores de pantalla lo anuncian.

Notion

Escribe /embed, elige Embed y pega la URL del atributo src del código de inserción (no la etiqueta iframe completa). Notion carga los contenidos insertados a través de su propio servicio de embeds; si una página no se puede mostrar integrada, Notion muestra un error en su lugar. En ese caso, pega el enlace para compartir como marcador: un clic abre el diagrama en vivo.

Confluence

Confluence Cloud no acepta HTML en bruto ni código iframe en el editor. Pega el enlace para compartir, que Confluence convierte en un enlace o una tarjeta. Si tu organización permite apps de Marketplace, una app de macro iframe o HTML puede mostrar la inserción dentro de la página.

Confluence Data Center tiene una macro HTML que los administradores pueden habilitar. Permite que cualquiera con permiso de edición añada HTML y JavaScript arbitrarios a las páginas, por eso muchas organizaciones la mantienen desactivada. Pregunta a tu administrador antes de contar con ella.

README de GitHub y Markdown en repositorios

GitHub no renderiza iframes en Markdown, así que en un README no es posible una inserción en vivo. El mejor sustituto es un SVG exportado, versionado junto al código y enlazado al diagrama en vivo:

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

Los lectores ven la imagen en el README y un clic abre la versión actual. Añade "¿Se actualizó la exportación del diagrama?" a tu plantilla de pull request, y haz commit también de la exportación JSON si quieres revisar los cambios del diagrama como datos.

Slack, Teams, Jira y correo

Pega el enlace para compartir. Siempre abre la versión actual, así que un mensaje antiguo en un hilo no apunta a una imagen antigua.

Prácticas para que siga funcionando

• Un diagrama, muchos enlaces. Nunca copies un diagrama en un segundo archivo para "hacer una versión para la wiki".
• Pon el título, el responsable y la fecha de la última revisión en el lienzo. Las inserciones y los enlaces muestran el lienzo, no los metadatos de tu página.
• Comparte con intención. Un enlace o una inserción en una página pública hace público el diagrama. Mantén la arquitectura interna en páginas internas y renueva el enlace si se filtra.
• Usa las exportaciones como respaldo, no por costumbre. Cada exportación es una copia que puede quedar desactualizada.

Este es todo el montaje en un solo lienzo:

Hazlo en Archboard

Abre cualquier diagrama, elige Compartir y activa el enlace; en Pro, activa también la inserción. Si vas a empezar un diagrama para tu documentación, las plantillas y los ejemplos son una forma rápida de arrancar, y el diagrama de arriba usa nueve cajas del pack Básico, dentro del plan Free.

Preguntas frecuentes

¿Puedo insertar un diagrama en el plan Free? Free incluye el enlace para compartir con marca. La inserción por iframe forma parte de Pro y Enterprise.

¿Los espectadores necesitan una cuenta? No. Cualquiera que tenga el enlace o abra la página con la inserción puede ver el diagrama en vivo. No puede editarlo.

¿Puedo dejar de compartir más adelante? Sí. Renueva el enlace o el código de inserción para invalidar el anterior, o desactiva el uso compartido para desconectar a los espectadores de inmediato.

¿Un SVG exportado se actualiza cuando cambia el diagrama? No. Las exportaciones son copias. Vuelve a exportar cuando cambie el diagrama, o usa un enlace o una inserción siempre que sea posible.

¿Por qué mi inserción muestra un error en Notion o Confluence? Ambas herramientas controlan qué se puede insertar. Usa en su lugar el enlace para compartir como marcador o tarjeta, o pregunta a tu administrador por apps de inserción.

Empieza gratis — un puesto, sin tarjeta de crédito.