Creación de diagramas Markdown

Los diagramas son muy importantes en la documentación técnica, ya que nos ayudan a:

  • Visualizar relaciones de datos complejas
  • Mostrar arquitecturas de sistemas y flujos de trabajo
  • Expresar ideas y conceptos con mayor claridad

Herramientas comunes para diagramas Markdown

Mermaid

Mermaid es una de las herramientas de diagramas Markdown más populares; te permite generar varios diagramas usando una sintaxis de texto simple.

Tipos de diagramas compatibles:

  • Diagrama de flujo (Flowchart)
  • Diagrama de secuencia (Sequence Diagram)
  • Diagrama de clases (Class Diagram)
  • Diagrama de estados (State Diagram)
  • Diagrama de Gantt (Gantt Chart)
  • Gráfico circular (Pie Chart)

Diagrama de flujo

```mermaid
graph TD
    A[开始] --> B{条件判断}
    B -->|Yes| C[执行操作A]
    B -->|No| D[执行操作B]
    C --> E[结束]
    D --> E
```

Dirección del diagrama de flujo

  • TDoTB:de arriba hacia abajo
  • BT:de abajo hacia arriba
  • RL:de derecha a izquierda
  • LR:de izquierda a derecha

Forma de los nodos

  • A[方形]:rectángulo
  • B(圆角矩形):rectángulo redondeado
  • C{菱形}:rombo (decisión)
  • D((圆形)):círculo
  • E>旗帜形]:forma de bandera

Tipo de líneas de conexión

  • -->Flecha de línea sólida
  • -.->Flecha de línea discontinua
  • ==>Flecha de línea sólida gruesa
  • --Línea sólida
  • -.Línea discontinua

Diagrama de secuencia y diagrama de Gantt

Diagrama de secuencia (Sequence Diagram)

```mermaid
sequenceDiagram
    participant A as 用户
    participant B as 系统
    participant C as 数据库
    
    A->>B: 登录请求
    B->>C: 验证用户信息
    C-->>B: 返回验证结果
    B-->>A: 登录成功/失败
```

Puntos clave de la sintaxis del diagrama de secuencia:

  • participantDefinir participantes
  • ->>Flecha de línea sólida
  • -->>Flecha de línea discontinua
  • noteAñadir comentarios

Diagrama de Gantt (Gantt Chart)

```mermaid
gantt
    title 项目开发计划
    dateFormat  YYYY-MM-DD
    section 设计阶段
    需求分析      :done,    des1, 2024-01-01,2024-01-15
    UI设计       :active,  des2, 2024-01-10, 30d
    section 开发阶段
    前端开发      :         dev1, after des2, 45d
    后端开发      :         dev2, 2024-02-01, 60d
    section 测试阶段
    单元测试      :         test1, after dev1, 15d
    集成测试      :         test2, after dev2, 10d
```

Puntos clave de la sintaxis del diagrama de Gantt:

  • titleEstablecer título
  • dateFormatDefinir formato de fecha
  • sectionDefinir fases
  • Estado de las tareas:done(completado)active(en curso)crit(crítico)

Gráfico circular

```mermaid
pie
    title 浏览器市场份额
    "Chrome" : 65
    "Safari" : 15
    "Firefox" : 10
    "其他" : 10
```


Explicación detallada de los tipos de diagramas

Diagrama de flujo (Flowchart)

El diagrama de flujo es el tipo de diagrama más utilizado, sirve para mostrar procesos o flujos de algoritmos.

Ejemplo de Mermaid:

```mermaid
graph LR
    A[开始] --> B{条件判断}
    B -->|是| C[执行操作1]
    B -->|否| D[执行操作2]
    C --> E[结束]
    D --> E
```

Explicación de la sintaxis:

  • graphDeclarar diagrama de flujo
  • LRIndica disposición de izquierda a derecha (opcional TB/RL/BT)
  • -->Indica conexión con flecha
  • []Indica nodo rectangular
  • {}Indica nodo condicional en forma de rombo

Diagrama de secuencia (Sequence Diagram)

El diagrama de secuencia muestra el orden de las interacciones entre objetos.

Ejemplo de Mermaid:

```mermaid
sequenceDiagram
    participant 用户
    participant 系统
    用户->>系统: 登录请求
    系统-->>用户: 验证请求
    用户->>系统: 提交凭证
    系统-->>用户: 登录成功
```

Explicación de la sintaxis:

  • participantDefinir participantes
  • ->>Indica flecha de línea sólida
  • -->>Indica flecha de línea discontinua

Diagrama de clases (Class Diagram)

El diagrama de clases se usa en el diseño orientado a objetos para mostrar clases y sus relaciones.

```mermaid
classDiagram
    class 用户 {
        +用户名: string
        +密码: string
        +登录()
    }
    
    class 订单 {
        +订单号: int
        +创建日期: date
        +计算总价()
    }
    
    用户 "1" --> "n" 订单
```

Técnicas avanzadas

1. Personalización del tema

Mermaid permite personalizar el estilo de los diagramas:

```mermaid
%%{init: {'theme': 'forest'}}%%
pie
    title 自定义主题
    "项目A" : 30
    "项目B" : 50
    "项目C" : 20
```

2. Diagramas interactivos

Algunas herramientas admiten añadir funciones interactivas:

```mermaid
graph TD
    A[点击我] --> B[显示详细信息]
    click A "https://www.example.com" "这是提示文本"
```

3. Exportar diagramas

La mayoría de las herramientas permiten exportar diagramas como:

  • Imagen PNG
  • Gráfico vectorial SVG
  • Documento PDF

Compatibilidad de herramientas

Herramienta/Plataforma Mermaid PlantUML Graphviz
GitHub ✔ ✖ ✖
GitLab ✔ ✔ ✔
VS Code Plugin Plugin Plugin
Typora ✔ ✖ ✖
Obsidian Plugin Plugin Plugin

Mejores prácticas

  1. Mantener la simplicidad:los diagramas deben ser claros y sencillos, evitando demasiados detalles
  2. Estilo coherente:los diagramas del mismo documento deben mantener un estilo coherente
  3. Añadir explicaciones:añadir explicaciones textuales para diagramas complejos
  4. Control de versiones:los diagramas en formato de texto se integran bien con Git
  5. Probar la representación:probar la visualización de los diagramas en diferentes plataformas

Preguntas frecuentes

Q1: ¿Por qué no se muestra mi diagrama?

  • Comprueba si has utilizado la sintaxis correcta
  • Confirma que tu editor/plataforma de Markdown sea compatible con esa herramienta de diagramas
  • Revisa si hay errores de sintaxis

Q2: ¿Cómo aprender la sintaxis de estos diagramas?

Q3: ¿Hay algún editor visual?

Otras extensiones