Antes de adentrarnos en disposiciones arquitectónicas específicas como diagramas de flujo complejos o cronogramas de secuencia, es esencial comprender las reglas fundamentales que rigen elManual de Mermaid. Mermaid se basa en un sistema de notación de texto limpio e intuitivo. Una vez que entiendas cómo el motor inicializa un tipo de lienzo, nombra los componentes estructurales y enruta las flechas direccionales, escribir cualquier disposición de sistema complejo se vuelve completamente natural.
Esta breve introducción cubre las mecánicas de sintaxis estructural global que se aplican en casi todos los tipos de diagramas de Mermaid dentro del entorno de trabajo VPasCode.
1. Los envolventes obligatorios del tipo de diagrama
Cada bloque individual de código de Mermaid debe comenzar declarando explícitamente su arquetipo de diagrama en la primera línea. Esto indica al analizador de VPasCode exactamente qué motor estructural debe activar en tu lienzo de vista previa:
graph TD— Especifica una disposición de diagrama de flujo organizada de arriba hacia abajo.sequenceDiagram— Especifica un gráfico de línea de tiempo cronológica de tiempo de ejecución.classDiagram— Especifica un plano de software orientado a objetos estructural.
A diferencia de otros motores de texto a diagrama, Mermaid no requiere etiquetas de cierre al final. El analizador simplemente lee la declaración estructural en la primera línea y compila todo lo anidado directamente debajo dentro del contenedor de tu bloque de código.
2. Declaración de elementos: IDs frente a etiquetas de visualización
Al modelar un sistema de software, crearás diversos elementos estructurales como componentes, bases de datos o microservicios. En Mermaid, declaras un elemento definiendo una ID alfanumérica interna corta, seguida inmediatamente por un estilo de corchetes que controla su forma visual, y un nombre de visualización amigable para el usuario:
microservice_id[API de procesamiento de pagos]
db_id[(SQL de transacciones de usuario)]¿Por qué esta es una buena práctica: Usar una ID interna corta y limpia (comomicroservice_id) hace que dibujar líneas de relación sea mucho más rápido más adelante. Si en algún momento necesitas cambiar la etiqueta visible para el cliente de “API de procesamiento de pagos” a “Servicio de caja global”, solo tendrás que editarla en la única línea donde se declara, en lugar de actualizar decenas de líneas en todo tu script.
3. Dominar las flechas de relación y la ruta direccional
Las conexiones entre nodos del sistema se dibujan usando combinaciones de guiones (-), signos de igualdad (=), y corchetes de flecha (>). El estilo de tus líneas te da un control implícito sobre cómo el motor de diseño automático escala tu diagrama:
A --> Bdibuja una flecha dirigida estándar que apunta desde el elemento A directamente hacia el elemento B.A --- Bdibuja una línea de enlace plana e indirigida sin punta de flecha, ideal para asociaciones simples.A -.-> Bcrea una línea de dependencia punteada, que es el estándar de la industria para indicar dependencias asíncronas o webhooks de red.A ==> Bcrea una línea de conexión gruesa y en negrita, perfecta para resaltar rutas principales de procesamiento de datos o enlaces de infraestructura crítica.
4. Agregar contexto en línea: etiquetas y comentarios de código
La documentación clara depende en gran medida de colocar el contexto adecuado alrededor de tus líneas visuales y scripts de texto:
Etiquetado de líneas de conexión
Puedes agregar texto explicativo directamente a cualquier línea de conexión insertando la cadena de texto entre dos conjuntos de guiones, o añadiendo un carácter de tubería (“|Texto|) justo después de tu asignación de relación:
client_id -- "POST HTTPS /v1/checkout" --> api_id
client_id --> |POST HTTPS /v1/checkout| api_idEscribir comentarios de código
Si deseas dejar una nota administrativa, crédito de diseño o explicación arquitectónica dentro de tu archivo de script sin renderizar una caja visual en la cuadrícula, utiliza signos de porcentaje dobles (%%). Esto indica al motor que omita completamente el análisis de esa línea:
%% TODO: Debemos actualizar esta caja de límite una vez finalice la migración de DevOps
[Monolito heredado] --> [Nuevo Microservicio]