Sådan redigeres Markdown + UML i Visual Studio Code

Har du hader at tegne diagrammer til teknisk dokumentation? Det ser ud til, at ikke før du er færdig med et kladde, kommer nye forbedringer, der tvinger dig til ikke kun at ændre teksten, men også billedet. Hvis du bruger et traditionelt tegneværktøj, kan det være kedeligt.

UML

UML er akronymet for Universal Modelling Language, et forsøg på at standardisere en ikonografi til softwaredesign, der først dukkede op for 25 år siden. Selvom det måske ikke har levet op til designernes større ambitioner, tilbyder det stadig en konsekvent måde at visualisere forskellige aspekter af softwaredesign på.

PlantUML

Det er kedeligt at tegne UML-diagrammer, men hvad hvis du i stedet kunne beskrive et UML-diagram tekstmæssigt på en måde, som du kunne inkludere det direkte i et Markdown-baseret dokument, se både diagrammer og formateret tekst i en forhåndsvisning, mens du redigerer det, og derudover kan eksportere Markdown som HTML eller PDF? Din tekst og diagrammer er problemfrit integreret i en fil. Det er her PlantUML kommer ind ...

VS-kode

Visual Studio Code (aka VS Code) er blevet en populær editor til forskellige computersprog, herunder Markdown . Med en enkelt udvidelse kan du visualisere UML-diagrammer i VS Codes eksempelpanel.

Denne udvidelse kaldes plantuml , og du kan installere den enten ved at søge efter den i udvidelsespanelet (klik på udvidelsesikonet):

klik derefter på installation, eller blot ved at køre følgende fra en terminalrude (Ctrl + 'får dig en):

ext install plantuml

Du bliver også nødt til at have en version af Java installeret med JAVA_HOMEet miljøvariabelsæt eller en eksekverbar sti med java- binærplaceringen.

Tilføjelse af PlantUML til din Markdown

Med udvidelsen installeret kan du nu indsætte UML-diagrammer ved hjælp af PlantUML-sprog. Et eksempel:

## 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 ```

Og nu når jeg åbner VS-kodens eksempelrude:

Hvad mere er, diagrammet i ruden Eksempel holdes synkroniseret med UML som beskrevet i Markdown-dokumentet. Ingen grund til at opdatere Preview-ruden.

Det er godt, men hvad hvis du vil eksportere et diagram inden for Markdown? Til det har du brug for lidt hjælp fra dine venner ...

Eksport til SVG eller PNG

For at eksportere individuelle diagrammer er jeg nødt til at installere GraphViz , som er "open source graf visualiseringssoftware". Det fungerer sammen med tidligere installeret plantuml- udvidelse. I modsætning til plantuml er det ikke en VS-kodeudvidelse, men en eksekverbar.

Sådan eksporteres til SVG eller PNG:

  1. placer markøren inden for den ønskede PlantUML-tekst,
  2. åbn kommandopaletten (Ctrl-Shift-P på min pc); eller højreklik og vælg Command Palette ...
  3. Vælg "PlantUML: Eksporter aktuelt diagram"

Du kan vælge PNG-, SVG- eller andre formater. ** Her er PNG- og SVG-versionerne af diagrammet vist i ruden Eksempel ovenfor:

Du har også mulighed for at eksportere alle diagrammer i et Markdown-dokument (kommandopaletteindstilling "PlantUML: Eksporter aktuelle fildiagrammer"), som opretter separate billedfiler til hvert diagram. For eksempel er mit Markdown-dokument navngivet, basic.mdog når jeg eksporterer alle diagrammer (der er tre) som SVG, genereres tre billedfiler:

  • basic.svg (det allerede viste sekvensdiagram)
  • basic-1.svg (et klassediagram)
### 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 (et tilstandsdiagram)
## 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 ```

** Andre formater, jeg har forsøgt at eksportere ved hjælp af netop denne udvidelse, er HTML, som mislykkedes med en Java-fejl:

java.lang.UnsupportedOperationException: HTML

og PDF, som mislykkes med en lignende fejl. Ingen problemer! Jeg har løsninger, som det vil blive vist.

Yderligere funktionalitet

Der er en anden nyttig VS- kodeudvidelse kaldet Markdown Preview Enhanced . Dette tilføjer en anden preview-rude ud over VS Codes oprindelige Preview-rude.

Af en eller anden grund vises to versioner i min udvidelsesrude, da jeg søgte efter den; Jeg valgte det seneste:

Nu ser du to forhåndsvisningskontroller over dit Markdown-dokument:

Når ruden er åben, kan du nu højreklikke på den og eksportere til forskellige formater, såsom HTML eller PDF.

Eksporter til PDF

Markdown Preview Enhanced er i stand til at arbejde med Chrome-browseren for at generere PDF-dokumenter gennem Puppeteer-driveren. Alt hvad du skal gøre er at give noget forreste spørgsmål i din markdown, der styrer Puppeteer, hvordan du layouter 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 ... 

Forsiden vises hverken i den almindelige VS-kode-eksempelrude eller i Markdown Preview Enhanced-ruden.

For at eksportere skal du blot højreklikke i ruden Markdown Preview Enhanced og vælge Chome (Puppeteer) -> PDF:

Det tager et par sekunder, men PDF'en genereres til sidst, og din standardbrowser åbnes (ikke nødvendigvis Chrome) med PDF-dokumentet vist.

UML er et rigt sprog, og PlantUML understøtter meget af det ud over nogle ikke-UML-diagrammer. Du behøver ikke at være UML-ekspert for at formidle ideer gennem diagrammer, men du vil finde dine diagrammer lettere at ændre gennem tekst end gennem et tegneværktøj. Derudover er muligheden for at integrere diagrammer i din Markdown-dokumentation og eksportere den i forskellige formater et stort plus.