whiteboard

¿Qué hace whiteboard?

Convierte una explicación en un diagrama que el usuario pueda ver, guardar y pegar en cualquier lugar. Tú escribes el código fuente del diagrama; scripts/render.mjs lo renderiza con el CLI instalado localmente del usuario y te dice exactamente qué está mal cuando no se analiza correctamente.

Flujo de trabajo

1. Elige el tipo de diagrama y el lenguaje. Por defecto, usa Mermaid. Usa D2 para diagramas de arquitectura grandes con contenedores anidados; PlantUML solo cuando el usuario lo solicite o el proyecto ya lo use. Consulta references/syntax.md para la sintaxis de cada tipo.

2. Lee antes de dibujar. Cuando el diagrama describe código, lee el código primero. Dibuja lo que existe, con nombres reales, no una imagen genérica. Para solicitudes de todo el proyecto (arquitectura, flujo de control, modelo de datos) sigue references/modes.md.

3. Escribe el código fuente y renderízalo. Pásalo por la entrada estándar (stdin) con un título corto (como máximo 80 caracteres). El título nombra los archivos, así que reutilízalo cuando redibujes el mismo diagrama:

   node <directorio-habilidad>/scripts/render.mjs --title "Secuencia de pago" <<'EOF'
   sequenceDiagram
     Navegador->>API: POST /checkout
     API->>Pagos: charge(card)
     Pagos-->>API: ok
     API-->>Navegador: 201 Created
   EOF
   

   <directorio-habilidad> es la carpeta donde se encuentra este archivo. Añade --language d2 o --language plantuml para esos lenguajes. En Windows, o cuando los heredocs sean incómodos, escribe el código fuente en un archivo temporal y pasa --file <ruta> en su lugar.

4. Corrige y vuelve a ejecutar si falla. El código de salida 1 significa que el renderizador rechazó el código fuente; el mensaje indica la línea. Corrige esa línea y ejecuta el mismo comando de nuevo. No entregues al usuario un diagrama que no se haya renderizado. Las correcciones comunes se enumeran al final de references/syntax.md.

5. Informa brevemente. Di qué muestra el diagrama y da las rutas de los archivos que el script haya impreso (por ejemplo, diagrams/secuencia-pago.svg). Si el usuario quiere pegarlo en un README, issue o wiki, proporciona el código fuente en un bloque ```mermaid: GitHub, GitLab y Notion lo renderizan.

Referencia del script

Opción	Uso
--title <texto>	Obligatorio. Nombra los archivos: diagrams/<slug>.svg y el código fuente junto a él.
--language <nombre>	mermaid (por defecto), d2 o plantuml.
--file <ruta>	Lee el código fuente de un archivo en lugar de la entrada estándar.
--out <directorio>	Carpeta de salida; por defecto diagrams en la carpeta actual.
--png	También escribe un PNG (presentaciones, aplicaciones de chat, terminales que muestran imágenes).
--theme <nombre>	default, neutral, dark o forest.
--config <archivo>	Un archivo JSON de configuración de Mermaid, para colores y fuentes del equipo.
--check	Solo validación; no escribe nada.
--open	Abre el SVG en el visor predeterminado del usuario. Úsalo cuando el usuario quiera ver el diagrama ahora.
--share	Sube el código fuente a un Gist secreto de GitHub e imprime el enlace. Ejecútalo solo después de que el usuario haya pedido compartir y haya aceptado la subida.
--json	Resultado legible por máquina.
--doctor	Verifica Node, cada renderizador y el CLI de GitHub, y dice qué instalar.

Códigos de salida: 0 renderizado, 1 código fuente rechazado (corrígelo y vuelve a ejecutar), 2 argumentos incorrectos, 3 renderizador no instalado.

Los diagramas nunca leen archivos locales, variables de entorno o URL en la imagen:

• Mermaid se renderiza en una página de navegador aislada que no puede cargar nada de la red o el disco. Cualquier sintaxis de Mermaid funciona, pero las imágenes remotas o locales y los recursos CSS permanecen en blanco; incrusta una imagen como URL data: si debe aparecer.
• PlantUML: se rechazan directivas distintas de las simples (!define, !if, !procedure, !$var, !theme <nombre>, !include <stdlib>…), %getenv y similares incorporados, y <img:…>. En su lugar, incrusta el contenido.
• D2: se rechazan las importaciones @. Los diagramas con iconos, cadenas de bloque, HTML o URL se renderizan solo en SVG, donde permanecen como enlaces.

Solo si el usuario solicita explícitamente inclusiones o imágenes externas, vuelve a ejecutar con WHITEBOARD_ALLOW_INCLUDES=1.

Redibujar con el mismo título conserva los archivos anteriores en diagrams/.versions/<slug>/<n>/, por lo que iterar sobre un diagrama nunca pierde la versión anterior.

Cuando falta un renderizador

El código de salida 3 imprime el comando de instalación. Dile al usuario qué ejecutar y no instales paquetes globales por tu cuenta a menos que te lo pidan:

• Mermaid: npm i -g @mermaid-js/mermaid-cli
• D2: brew install d2, o consulta https://d2lang.com/tour/install
• PlantUML: brew install plantuml o apt install plantuml (necesita Java)

Si un renderizador está instalado pero no se encuentra (común en aplicaciones de escritorio que se inician sin el PATH del shell de inicio de sesión), establece WHITEBOARD_MMDC, WHITEBOARD_D2 o WHITEBOARD_PLANTUML a su ruta completa. El renderizado de Mermaid usa el navegador y el paquete de Mermaid que vienen con mermaid-cli; si el script encuentra mmdc pero no su paquete, establece WHITEBOARD_MERMAID_CLI_DIR a la carpeta @mermaid-js/mermaid-cli. Cuando no se pueda instalar nada, proporciona el código fuente de Mermaid en un bloque de código para que aún se renderice en GitHub y di que no fue revisado por un renderizador.

Buenos diagramas

• Una idea por diagrama. Divide cualquier cosa con más de unos 15 nodos o 20 mensajes en un diagrama de visión general más diagramas de detalle.
• Etiqueta cada borde con lo que fluye o sucede (HTTP, publica OrderPlaced, 1..*).
• Usa los nombres del código: nombres de clases, módulos y servicios, endpoints reales, tablas reales.
• Elige el tipo que coincida con la pregunta: quién llama a quién a lo largo del tiempo → secuencia; cuáles son las partes → arquitectura/diagrama de flujo; cómo son los datos → ER o clase; cómo cambia algo con el tiempo → estado.
• Mantén el texto corto dentro de los nodos; pon el detalle en las etiquetas de los bordes o notas.