Cómo editar Markdown + UML en Visual Studio Code

¿Odias dibujar diagramas para documentación técnica? Parece que apenas terminas un borrador, aparecen nuevos refinamientos que te obligan a cambiar no solo el texto, sino también la imagen. Si está utilizando una herramienta de dibujo tradicional, eso puede resultar tedioso.

UML

UML es el acrónimo de Universal Modeling Language, un esfuerzo por estandarizar una iconografía para el diseño de software que apareció por primera vez hace 25 años. Aunque quizás no ha estado a la altura de las ambiciones más amplias de sus diseñadores, todavía ofrece una forma consistente de visualizar varias facetas del diseño de software.

PlantUML

Dibujar diagramas UML es tedioso, pero ¿qué pasaría si en su lugar pudiera describir un diagrama UML textualmente, de manera que pudiera incluirlo directamente en un documento basado en Markdown, ver tanto los diagramas como el texto formateado en una vista previa mientras lo está editando, y Además, ¿puede exportar el Markdown como HTML o PDF? Su texto y diagramas se integran perfectamente en un archivo. Ahí es donde entra PlantUML ...

Código VS

Visual Studio Code (también conocido como VS Code) se ha convertido en un editor popular para varios lenguajes informáticos, incluido Markdown . Con una sola extensión, puede visualizar diagramas UML en el panel de vista previa de VS Code.

Esa extensión se llama plantuml , y puede instalarla buscándola en el panel de extensiones (haga clic en el icono de la extensión):

luego haciendo clic en instalar, o simplemente ejecutando lo siguiente desde un panel de terminal (Ctrl + 'le da uno):

ext install plantuml

También necesitará tener alguna versión de Java instalada, con JAVA_HOMEuna variable de entorno configurada o una ruta ejecutable con la ubicación binaria de Java en ella.

Añadiendo PlantUML a su Markdown

Con la extensión instalada, ahora puede insertar diagramas UML usando el lenguaje PlantUML. Un ejemplo:

## uml: sequence diagram Here I will embed PlantUML markup to generate a sequence diagram. I can include as many plantuml segments as I want in my Markdown, and the diagrams can be of any type supported by PlantUML. ```plantuml @startuml skinparam backgroundColor #EEEBDC skinparam handwritten true actor Customer Customer -> "login()" : username & password "login()" -> Customer : session token activate "login()" Customer -> "placeOrder()" : session token, order info "placeOrder()" -> Customer : ok Customer -> "logout()" "logout()" -> Customer : ok deactivate "login()" @enduml ```

Y ahora, cuando abro el panel de vista previa de VS Code:

Además, el diagrama en el panel Vista previa se mantiene sincronizado con UML como se describe en el documento Markdown. No es necesario actualizar el panel de vista previa.

Eso es genial, pero ¿qué sucede si desea exportar un diagrama desde Markdown? Para eso necesitarás un poco de ayuda de tus amigos ...

Exportando a SVG o PNG

Para exportar diagramas individuales, necesito instalar GraphViz , que es un "software de visualización de gráficos de código abierto". Funciona en conjunto con la extensión plantuml instalada anteriormente. A diferencia de plantuml, no es una extensión de VS Code, sino un ejecutable.

Para exportar a SVG o PNG:

  1. coloque el cursor dentro del texto PlantUML deseado,
  2. abrir la paleta de comandos (Ctrl-Shift-P en mi PC); o haga clic derecho y seleccione Command Palette ...
  3. Elija "PlantUML: Exportar diagrama actual"

Puede elegir PNG, SVG u otros formatos. ** Aquí están las versiones PNG y SVG del diagrama que se muestra en el panel Vista previa, arriba:

También tiene la opción de exportar todos los diagramas dentro de un documento de Markdown (opción de paleta de comandos "PlantUML: Exportar diagramas de archivo actual"), que creará archivos de imagen separados para cada diagrama. Por ejemplo, mi documento de Markdown se nombra basic.mdy cuando exporto todos los diagramas (hay tres) como SVG, se generan tres archivos de imagen:

  • basic.svg (el diagrama de secuencia ya mostrado)
  • basic-1.svg (un diagrama de clases)
### uml: class diagram ```plantuml @startuml package "customer domain" #DDDDDD { class Contact { + email + phone } class Address { + address1 + address2 + city + region + country + postalCode + organization } note right of Address There are two types of addresses: billing and shipping end note class Customer { } Customer *-- Contact Customer *-- ShippingAddress Customer *-- BillingAddress Customer *--{ SalesOrder class ShippingAddress <> class BillingAddress <> class SalesOrder { + itemDescription + itemPrice + shippingCost + trackingNumber + shipDate } } @enduml ```
  • basic-2.svg (un diagrama de estado)
## uml: state diagram ```plantuml @startuml scale 600 width skinparam backgroundColor #FFEBDC [*] -> Begin Begin -right-> Running : Succeeded Begin --> [*] : Aborted state Running { state "The game runneth" as long1 long1 : Until you die long1 --> long1 : User interaction long1 --> keepGoing : stillAlive keepGoing --> long1 long1 --> tooBadsoSad : killed tooBadsoSad --> Dead : failed } Dead --> [*] : Aborted @enduml ```

** Otros formatos que he intentado exportar usando solo esta extensión son HTML, que falló con un error de Java:

java.lang.UnsupportedOperationException: HTML

y PDF, que falla con un error similar. ¡Sin preocupaciones! Tengo soluciones alternativas, como se mostrará.

Más funcionalidad

Hay otra extensión útil de VS Code llamada Markdown Preview Enhanced . Esto agrega un segundo panel de vista previa además del panel de vista previa nativo de VS Code.

Por alguna razón, aparecen dos versiones en mi panel de Extensión cuando lo busqué; Elegí lo último:

Ahora verá dos controles de vista previa sobre su documento de Markdown:

Con el panel abierto, ahora puede hacer clic derecho sobre él y exportar a varios formatos, como HTML o PDF.

Exportar a PDF

Markdown Preview Enhanced puede trabajar con el navegador Chrome para generar documentos PDF, a través del controlador Puppeteer. Todo lo que necesita hacer es proporcionar información preliminar en su rebaja que indique a Puppeteer cómo diseñar el PDF:

--- puppeteer: landscape: true format: "letter" timeout: 3000 # <= wait 3 seconds before rendering in browser --- # Overview This walks through a few of use cases, linking them to "classes", which are either simple data objects or objects with methods. --- # UML Diagrams ... 

La parte delantera no aparecerá ni en el panel de Vista previa de código VS normal ni en el panel Mejorado de vista previa de Markdown.

Para exportar simplemente haga clic con el botón derecho en el panel Mejorado de vista previa de Markdown y seleccione Chome (Titiritero) -> PDF:

Tarda unos segundos, pero el PDF finalmente se generará y se abrirá su navegador predeterminado (no necesariamente Chrome) con el documento PDF mostrado.

UML es un lenguaje rico y PlantUML admite gran parte de él, además de algunos diagramas que no son UML. No tiene que ser un experto en UML para transmitir ideas a través de diagramas, pero encontrará que sus diagramas son más fáciles de modificar a través del texto que a través de una herramienta de dibujo. Además de eso, la capacidad de incrustar diagramas en su documentación de Markdown y exportarlo en diferentes formatos es una gran ventaja.