Diagramas de Gantt en Mermaid: sintaxis, trampas y vuelta a un editor real

La sintaxis de una pasada

Un bloque gantt se abre con la palabra clave gantt y unas pocas líneas de cabecera, y después vienen encabezados section con líneas de tarea debajo. La sangría es convención, no gramática: Mermaid no se queja si la pierdes, pero el diff sí.

Una línea de tarea es un nombre, dos puntos y después campos separados por comas:

Nombre de tarea :etiqueta, id, inicio, duración

• Etiquetas — cualquiera de done, active, crit, milestone, en cualquier orden, y puedes apilar varias en la misma tarea. Son opcionales.
• id — una palabra suelta, sin espacios ni puntuación, necesaria solo si algo más se refiere a esta tarea.
• inicio — una fecha, o after algúnId, o se omite por completo para continuar justo detrás de la tarea anterior.
• duración — 5d, 2w, o una segunda fecha absoluta que fija el final.

Cabeceras que conviene conocer: dateFormat (cómo están escritas las fechas en tu archivo), excludes weekends, title y axisFormat (cómo se etiqueta el eje, con códigos al estilo strftime). Los campos se clasifican por su forma más que por su posición estricta, y por eso :done, aud, 2026-03-02, 5d y :aud, done, 2026-03-02, 5d funcionan los dos igual de bien.

Una advertencia que ahorra media hora de desconcierto: dateFormat y axisFormat no son el mismo parámetro escrito de dos maneras. El primero es entrada y el segundo es salida. Cambiar dateFormat no reetiqueta el eje; lo que hace es cambiar cómo se leen las fechas que ya has tecleado, con lo que un archivo perfectamente correcto puede pasar a interpretarse al revés.

Un ejemplo completo que puedes pegar en un README

Un bloque válido y completo para trabajo real: el lanzamiento de la app de reservas de Grupo Alcorta, una agencia de Valladolid, con el equipo de producto de Marta Iglesias. Usa secciones, fechas absolutas, cadenas de after, todas las etiquetas, un hito y fines de semana excluidos. Pégalo en un bloque delimitado mermaid dentro de cualquier Markdown de GitHub y se renderiza.

gantt
    title Lanzamiento app de reservas — Grupo Alcorta
    dateFormat YYYY-MM-DD
    axisFormat %d %b
    excludes weekends

    section Descubrimiento
    Auditoria del backend actual   :done, aud, 2026-03-02, 5d
    Especificacion funcional       :done, esp, after aud, 4d
    Revision con cliente           :active, rev, after esp, 2d

    section Construccion
    Servicio de identidad          :crit, ident, after rev, 10d
    Pantallas de reserva           :pant, after ident, 12d
    Pasarela de pago               :pago, after pant, 6d

    section Salida
    Pruebas en preproduccion       :pre, after pago, 5d
    Beta publica                   :milestone, beta, 2026-05-04, 0d
    Retirada de la version antigua :ret, after beta, 2w

Referencia de la línea de tarea

Cada campo y modificador, qué hace y cómo se ve en la práctica.

Cuatro cosas que te van a morder

1. Las duraciones incluyen el día de inicio. 5d desde el lunes día 5 llega hasta el viernes día 9, no hasta el 10. Un error de uno aquí desplaza todas las tareas del archivo y aun así se renderiza perfectamente, que es el peor modo de fallo posible: nada parece roto. La entrega sigue apareciendo en su sitio hasta el día en que alguien intenta cumplirla.

2. after junto con excludes weekends es donde viven los errores de verdad. Si una predecesora termina un viernes, su sucesora empieza el lunes, no el sábado. Cualquier herramienta que resuelva after sumando un día natural colocará tareas en fin de semana dentro de un archivo que lo prohíbe explícitamente, y a partir de ahí todas las fechas de aguas abajo van a la deriva. La nuestra lo hizo, brevemente. El arreglo pasa la aritmética por el calendario laboral para que la importación coincida con lo que Mermaid dibuja, y la prueba que lo vigila comprueba la propiedad y no fechas concretas: ningún inicio ni fin derivado puede caer en un día excluido. Las fechas que escribiste tú a mano se quedan donde las pusiste, sea fin de semana o no. Mover en silencio la fecha explícita de un autor es el tipo equivocado de amabilidad.

3. No hay forma de escapar caracteres. Los dos puntos abren la lista de campos y la coma separa campos, así que Fase 2: diseño, revisión se convierte en una tarea llamada «Fase 2» con campos basura. Mantén los dos puntos, las comas y los puntos y comas fuera de los nombres de tarea. Es la razón de que en el ejemplo de arriba los nombres estén escritos sin ellos. Al exportar sustituimos esos caracteres por espacios antes que emitir una línea que no se va a poder interpretar.

4. Una duración ilegible pasa a cero en silencio. Escribe 3dd y obtendrás una barra de longitud cero en lugar de un error. Repasa el diagrama en busca de tareas invisibles después de cualquier edición masiva: no aparecen en ningún sitio, ni siquiera como una línea vacía.

Los límites de un formato de diagrama

Mermaid gantt es un lenguaje de representación, no un motor de planificación, y la diferencia salta a la vista en cuanto quieres que el gráfico responda a una pregunta en lugar de ilustrar una respuesta que ya tenías.

• Sin recursos. No hay campo para quién hace el trabajo, ni coste, ni esfuerzo, ni unidades. No puedes sobreasignar a nadie en Mermaid porque Mermaid no sabe que exista nadie.
• Sin holgura y sin ruta crítica calculada. crit es un color que aplicas a mano. Nada recorre el grafo de dependencias, ni calcula fechas tempranas y tardías, ni te dice qué cadena manda sobre la fecha de fin. Un diagrama con todas las barras marcadas crit es tan válido como uno sin ninguna.
• Sin línea base. No hay dónde guardar lo que decía el plan el mes pasado, así que no hay desviación que enseñar ni retraso que medir.
• Solo fin-inicio. after es FS con desfase cero. Inicio-inicio, fin-fin, inicio-fin y cualquier desfase o adelanto no tienen dónde ir. Los planes reales están llenos de «empezar a probar tres días después de que arranque el desarrollo»: en Mermaid eso se convierte en una fecha fija y el enlace desaparece.
• Sin porcentaje de avance. Una tarea al 40 % y otra al 90 % son las dos simplemente active.
• Secciones planas. No hay grupos anidados, así que una EDT de más de un nivel se aplana al entrar.

Nada de esto lo convierte en un mal formato. Lo convierte en un formato de publicación: excelente para enseñar un calendario, inútil para deducirlo. Y por eso importa la ida y vuelta.

Editar visualmente y pegar el texto de vuelta

Herramientas que renderizan Mermaid hay muchas. Lo que faltaba es la dirección contraria: arrastrar barras y recuperar la sintaxis.

1. Pega o abre tu diagrama en gantts.app — un archivo .mmd, o un .md con un bloque delimitado; los dos funcionan. Detecta el bloque gantt por su contenido, no por la extensión.
2. Comprueba el Calendario laboral. excludes weekends enciende el calendario, y ahí es donde añades los festivos que Mermaid no conoce: los nacionales, los de tu comunidad y el puente del convenio.
3. Arrastra, enlaza y cambia fechas como en cualquier otro gráfico. Con Ajustar mueves un extremo de la barra y con Mover la desplazas entera sin tocar la duración.
4. Activa Ruta crítica. Lo que se raya no es lo que decía crit en el archivo, sino lo que sale de recorrer las dependencias que acabas de importar.
5. Si el plan te ha quedado con huecos porque las fechas venían clavadas del archivo, pulsa Reprogramar para compactar cada tarea a su fecha legal más temprana.
6. Abre ⬇ Exportar ▸ 🧜 Mermaid gantt (texto). Ahí tienes Copiar al portapapeles si vas directo al README, o Descargar .mmd si el diagrama vive en su propio archivo dentro del repositorio.
7. Pega, revisa el diff y haz commit. El bloque sale con la misma forma con la que entró, así que el diff enseña lo que ha cambiado de verdad y no un reformateo completo.

La ida y vuelta pierde información de una forma conocida y aburrida. El avance convierte el 100 % en done y cualquier valor entre 1 y 99 en active al salir; active vuelve a entrar como 50 %, una suposición que se te comunica en un aviso en lugar de dejar que la descubras en un informe de seguimiento tres semanas después. Los enlaces que no se pueden escribir como after —cualquiera con desfase, o cualquier relación SS, FF o SF— caen a fechas absolutas, que siguen siendo correctas aunque dejen de ser mantenibles.

Hay una asimetría deliberada, y no es un fallo: crit se exporta pero nunca se importa. Al salir es un valor derivado —el editor calculó la ruta crítica a partir del grafo de dependencias, así que la etiqueta es cierta en el momento en que se escribe—. Al entrar es una palabra que alguien tecleó en un archivo que puede llevar semanas sin tocarse, y fiarse de ella permitiría que un diagrama viejo pintara de rojo una cadena que ya no es crítica. Así que se escribe y luego se ignora: la ruta crítica que ves después de importar está recalculada, no afirmada.

Un efecto secundario útil si redactas calendarios con un LLM: pídele sintaxis gantt de Mermaid, pega la respuesta y ya tienes un gráfico editable con ruta crítica calculada. Sin clave de API y sin servidor de por medio.

Preguntas frecuentes

Plantillas que usan esto

• Gestión de proyectos

Seguir leyendo

• Los cuatro tipos de dependencia
• Cómo se calcula la ruta crítica
• ¿Qué es un diagrama de Gantt?
• Ver todas las guías

Las guías que aún no se han traducido se abren en inglés.