3

The company I work in decided to store requirements in markdown format, in order to achieve simplicity, reference-ability, and previewing in TFS/Azure DevOps Server directly. Question is in previewing part in TFS/Azure Dev Ops Server. As I've found, it supports: HTML-tags, math formulas, images resizing, mentioning pull-requests, users, work-items and so on. But mermaid diagrams are not supported, though they are very useful to my mind to get common understanding of complex processes in shortest time.

I've installed pandoc, and that's a process: autogenerate HTML file for every updated md file in REPO Problem is that TFS/Azure DevOps Server won't accept previewing BASE64-encoded images, built-in in HMTL by pandoc.

So I've decided to do something like that:

  • for every updated md file create copy with postfix (***_IMG.md)
    • for every mermaid diagram
      • generate PNG image
      • save PNG image to a image folder
      • replace mermaid diagram with link to generated image
  • save altered md file

Could one possibley specify a list of software to reach this solution? I have not found answer on what instrument should I use, python I guess? But may be there some other alternatives?

Van Ng
  • 773
  • 1
  • 7
  • 17
  • I'm having the same problem here. If you could share your solution with us it would be much appreciated. – phifi Jun 12 '19 at 11:53
  • OK, I'll answer some code tips I've done as VBS code and describe a suggested workaround – Van Ng Jun 12 '19 at 20:52
  • I'm evaluating an alternative approach to mermaid with yUML. The integration with markdown is as easy as adding an tag and you don't need the whole process to replace mermaid diagrams with generated images. I'm gonna add an answer to this question if you find it usefull. eg. Add this img tag to your wiki to test it: – phifi Jun 13 '19 at 09:04
  • Interesting idea, with using side diagrams generating tool, thanks. I'll evaluate this variant for current circumstances – Van Ng Jun 13 '19 at 09:13

4 Answers4

3

It is easier than you think. The TFS/Azure DevOps Server Wiki is backed by a Git repository, so your process maybe something like:

  • git pull
  • scan repo files to find mermaid diagrams
  • generate JPG and replace the snippet with link to image
  • git commit
  • git push

It can be easily automated in a Pipeline and maybe an extension like Git Tools for Azure DevOps may make the job even simpler.

Giulio Vian
  • 8,248
  • 2
  • 33
  • 41
2

An alternative approach to include simple UML's to your TFS/Azure Dev Ops Wiki is yUML.me.

Just add a <img> Tag to your markdown including your UML syntax, eg.

<img src="http://yuml.me/diagram/scruffy/class/%2F%2F Cool Class Diagram, [Customer|-forname:string;surname:string|doShiz()]<>-orders*>[Order], [Order]++-0..*>[LineItem], [Order]-[note:Aggregate root{bg:wheat}].jpg">

This will add an image like this to your Wiki Page:

enter image description here

Many samples can be found here: https://yuml.me/diagram/scruffy/class/samples

Of course, this has some limitations such as the max length of an Uri, but i found this quite usefull for small UMLs and you can see the result live in the preview tab as you type in the Uml syntax.

I haven't tested it with AzureDevOps Server, but in TFS 2018 it works like a charm.

phifi
  • 2,783
  • 1
  • 21
  • 39
0

You can use the CLI version, https://github.com/mermaid-js/mermaid-cli With the CLI you can build .svg or .png renders from you .mmd file. (See also the Live Editor https://mermaid-js.github.io/mermaid-live-editor/, it may be easier for someone to create .mmd files)

tontonCD
  • 320
  • 2
  • 6
0

You could try this Azure DevOps Extension: Mermaid Renderer, which doesn't convert .md files, but instead adds .mmd support to Azure DevOps. It requires installation to your Azure DevOps organization.

enter image description here

(Edit: I see the OP asked about an old version of AZDO, but I'll leave this answer in place for others.)

matt_w
  • 1,096
  • 8
  • 8