Diagramas D2

Recurre a D2 cuando un diagrama necesita contenedores anidados y límites, un esquema de base de datos con claves primarias y foráneas, o una disposición que puedes ajustar cambiando de motor. Complementa la compatibilidad con Mermaid que ya existe en Jamdesk: sigue usando Mermaid para diagramas de flujo rápidos y pasa a D2 cuando la estructura se vuelve arquitectónica. Ambos se escriben en el mismo lugar — un bloque de código delimitado en tu Markdown — así que elegir uno es una cuestión de idoneidad, no de flujo de trabajo.

Uso básico

Usa un bloque de código delimitado con el identificador de lenguaje d2:

```d2
a -> b -> c
```

Tipos de diagramas

Arquitectura

Los diagramas de arquitectura representan cómo se conectan los servicios. Usa formas etiquetadas para mostrar la ruta de una solicitud a través de tu sistema.

```d2
Client: Web Client
API: API Server
Database: { shape: cylinder }

Client -> API: request
API -> Database: query
```

Contenedores

Los contenedores agrupan nodos relacionados. Anida formas dentro de llaves { } para modelar límites como una cuenta en la nube o un despliegue, y luego traza conexiones que crucen esos límites.

```d2
cloud: Cloud {
  api: API
  worker: Worker
}

queue: Message Queue

cloud.api -> queue: publish
queue -> cloud.worker: consume
```

Diagramas de secuencia

Los diagramas de secuencia muestran cómo se comunican los componentes a lo largo del tiempo. Define shape: sequence_diagram en un contenedor y enumera los mensajes en orden para documentar un flujo de API o de autenticación.

```d2
flow: {
  shape: sequence_diagram

  Client -> Server: request
  Server -> Database: query
  Database -> Server: results
  Server -> Client: response
}
```

Tablas SQL

Las formas de tabla SQL documentan un esquema de base de datos con columnas y tipos. Marca una columna con { constraint: primary_key } o { constraint: foreign_key } para mostrar las insignias PK y FK, y luego conecta una clave foránea con la tabla a la que hace referencia para mostrar la relación.

```d2
users: {
  shape: sql_table
  id: int { constraint: primary_key }
  email: varchar
}

orders: {
  shape: sql_table
  id: int { constraint: primary_key }
  user_id: int { constraint: foreign_key }
  total: decimal
}

orders.user_id -> users.id
```

Formas

Define una shape en cualquier nodo para cambiar cómo se renderiza:

Conexiones

Las conexiones definen la dirección y las relaciones entre nodos:

Elegir un motor de disposición

D2 incluye varios motores de disposición. El predeterminado es dagre. Para cambiar a ELK en grafos más densos, configúralo en el código fuente del diagrama mediante el bloque de configuración nativo de D2. No hay una prop de componente para esto en esta versión; el motor se selecciona en el propio diagrama.

```d2
vars: {
  d2-config: {
    layout-engine: elk
  }
}

ingress -> service -> database
```

Los diagramas anchos se desplazan horizontalmente dentro de su contenedor, de modo que un grafo denso sigue siendo legible sin desbordar la página.

Consejos de estilo

Para crear diagramas efectivos:

• Mantén cada diagrama compacto: divide un sistema grande en vistas enfocadas.
• Etiqueta las conexiones para que la relación quede clara de un vistazo.
• Agrupa los nodos relacionados en contenedores en lugar de un único grafo plano.
• Cambia al motor de disposición ELK para grafos densos con muchas conexiones.

D2 frente a Mermaid

Ambos lenguajes se renderizan en tiempo de build, así que la elección se reduce a la idoneidad:

• Elige D2 para diagramas de arquitectura e infraestructura, modelos SQL y ER, visuales de estilo boceto y cuando quieras poder elegir el motor de disposición.
• Elige Mermaid para diagramas de flujo, gráficos de Gantt y gráficos de Git. Ambos renderizan diagramas de secuencia; la sintaxis de secuencia de Mermaid es más rica en funciones, mientras que la de D2 mantiene el resto de tu diagrama en un solo lenguaje. Mermaid está ampliamente adoptado y cuenta con un amplio ecosistema.

Consulta la página Diagramas Mermaid para ver la sintaxis y ejemplos de Mermaid.

Más información

Para la referencia completa de la sintaxis D2, incluidos estilos, clases y animación, consulta la documentación oficial de D2.

¿Qué sigue?