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 abajoBT:de abajo hacia arribaRL:de derecha a izquierdaLR:de izquierda a derecha
Forma de los nodos
A[方形]:rectánguloB(圆角矩形):rectángulo redondeadoC{菱形}:rombo (decisión)D((圆形)):círculoE>旗帜形]: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 discontinuanoteAñ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ítulodateFormatDefinir formato de fechasectionDefinir 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 flujoLRIndica 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
- Mantener la simplicidad:los diagramas deben ser claros y sencillos, evitando demasiados detalles
- Estilo coherente:los diagramas del mismo documento deben mantener un estilo coherente
- Añadir explicaciones:añadir explicaciones textuales para diagramas complejos
- Control de versiones:los diagramas en formato de texto se integran bien con Git
- 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?
- Consulta la documentación oficial:
- Usa un editor en línea para practicar en tiempo real
Q3: ¿Hay algún editor visual?
- Mermaid Live Editor: https://mermaid.live
- PlantUML Server: http://www.plantuml.com/plantuml