Markdown Monster 4.5 - although a point release - is a major update to Markdown Monster. This releases replaces the main editor rendering surface with Microsoft's Monaco Editor from the original ACE Editor implementation.

ACE has been a wonderful platform to work with over the years and it has powered MM's editing experience for years. But Monaco brings a number of useful built-in editor features that previously required custom implementations or simply weren't practical to integrate.

Monaco is the editor core behind VS Code, but Markdown Monster's implementation sticks to the core editor engine features without many of the distracting pop up features and completions. For the most part the move to the new editor surface is not drastically different than the old ACE based interface and it most definitely doesn't make Markdown Monster just another VS Code variation.

What changes are some of the editor chrome features, like the scrollbars, minimap, find and replace and diff viewer that are native in Monaco. Additionally Monaco provides a more complete API to access internal features of the editor which allow more control over implementing custom features in the editor along with better documentation and better support for agents to help in improving Markdown Monster's feature set.

What's New in 4.5

So let's dive in and take a look what's new and improved.

Inline Diff Editing: See What Changed, Right Where You're Working

One of the primary reasons for the switch to Monaco was support for inline Diff editing. Diff editing is becoming increasingly more important in this age of agents where we often need to see changes to documents to compare old and changed text.

Markdown Monster internally uses several different operations for diff viewing:

• Startup Recovery Files (ie. hard exits or shutdowns before files were saved)
• Showing live diffs between the editor document and what was on disk when opened
• Showing Git Commit differences

Recovery File Detection is based on Backup files that show changes that were not saved for some reason. This could be a system or app crash, or any reason that caused the application to not finish a normal shutdown.

When you start back up you'd see something like this now in v4.5:

Figure 1 - Showing an inline Diff for non-saved changes from a previous run. You can edit the document in the Diff view.

You can jump out of Diff Mode into the regular editor view via the Tab or the Editor Context menu:

Figure 2 - Jumping out of Diff mode via Close Diff View returns you back into the standard editor without Diff

When you Close Diff View the Diff is effectively aborted. If you want to accept changes you have to individually accept the changes or all changes using the various hover options on the diff items.

To show changes of the current document vs. what's stored on disk you can use the Open in Diff Editor Tab or Editor Context menu option:

Figure 3 - Open in Diff Editor shows file differences between the edited file and what's on disk

Finally you can also open the Diff Editor on any file from the Folder Browser if it is managed by Git. When you open the file as Diff Editor from the Folder Browser the file then shows the uncommitted differences of the file.

These operations in the past brought an optionally configured external diff editor to view the differences, but this integrated view

Find and Replace That Doesn't Get in Your Way

The old ACE Editor find and replace dialog has always been clunky as it used very old school design that didn't fit into a desktop style UI. In the old version we ended up using custom CSS to restyle the Find and Replace popup, but due to the way ACE has this designed not everything was easy to style. In addition there were keyboard navigation with the original implementation that would in some scenarios transfer key operations pointing at the find dialog getting pushed into the editor.

With the adoption of Monaco we've inherited a much cleaner Find and Replace dialog that works correctly out of the box with navigation keystrokes. Monaco's finder also automatically highlights matches in the document (as did ACE) and also on the scrollbar so you can see at a glance where in the document matches live.

The familiar shortcuts still apply: Ctrl+F opens Find and Ctrl+H opens Replace.

Figure 4 - Monaco provides improved Find and Replace dialog behavior

An Optional Minimap for Longer Documents

Another nice improvement based on Monaco is the availability of an optional MiniMap of the document near the left scrollbar. Minimap provides a very dense layout of the document in the scrollbar area that lets you roughly see what the document looks like. It's useful in some situations to quickly jump to the appropriate document sections.

Personally I'm not a fan, but I know a lot of people who use this feature to navigate their documents and now that ability is hear courtesy of the Monaco editor integration.

If you like that visual overview, enable ShowMiniMap in the Options dialog. You can also enable it through the Editor.showMiniMap setting.

Figure 5 - Minimap gives you a compressed visual view of your document for navigation purposes

The Minimap is optional, and it's off by default, so you have to explicitly enable it in the settings.

Scrollbar Markers: A Quick View of Things to Review

Another benefit of Monaco is that information from inside the document can also appear as markers along the scrollbar.

The scrollbar highlights:

• Spelling Errors
• Current Selection Matches
• In Diff Mode, document changes

Figure 6 - Scrollbar markers show selection matches, spelling errors and document changes when in Diff mode

This feature is a subtle one, but it's useful when reviewing a long post. You can quickly get a feel where relevant text or spell errors live.

Razor and cURL Syntax Highlighting

This release also adds support for ASP.NET Razor and cURL syntax highlighting both inline in the editor and in the rendered preview output. Use razor or curl after the opening code fence to identify the language:

Figure 7 - Razor and cUrl syntax coloring both in the editor and previewer

Make sure your Hosting Platform Supports these formats Markdown Monster's preview uses highlightJs to produce highlighted syntax blocks, along with a custom extension to provide a toolbox with the syntax type and copy option.

One caveat is worth keeping in mind when publishing: The Markdown file doesn't carry its syntax highlighter with it. The language name on a code fence tells the receiving renderer what the block contains, but the website still needs a highlighter that supports that language. If your hosting platform doesn't support the syntax you may see generic code rendering.

You can incorporate MM's syntax coloring extensions in your own custom HTML. More info here...

Updated Highlight.js in the Preview

Speaking of highlighJs Markdown Monster now uses the latest version of this great JavaScript library. Due to some legacy code in the previous versions of Markdown Monster, we were using a quite old versions of highlightJs until this release. The new version adds a few additional syntaxes (see previous) and the highlighter runs more efficiently on the page for rendering, especially in very large documents.

Window Resizing now preserves Editor/Preview Size Ratio

This update also changes the Window resizing behavior for editor and preview panes. Previously the Preview pane was fixed in size and any Window resizing would only resize the Editor pane. In the new release the editor preview size ratio is preserved when the Window is resized so both editor and preview adjust size to stay in roughly the same layout ratio.

External Programs: More Useful Paths, Less Placeholder Guesswork

External Programs let you add your own Open... commands for tools outside Markdown Monster. They're handy for opening a file in another editor or launching a terminal where you're working.

Previously, these definitions used numeric placeholders such as {0} and {1}. Those continue to work, but looking at a command months later and remembering which number means which value isn't especially intuitive.

You can now use descriptive names instead:

(full docs here)

For an editor that accepts a file, row, and column, an argument string is much easier to understand when written as:

"ExternalPrograms": [
{
    "Name": "Open in VS Code",
    "Executable": "C:\\Program Files\\Microsoft VS Code\\Code.exe",
    "Args": "\"{CurrentFile}:{CurrentRow}:{CurrentColumn}\" -g \"{ProjectFolder}\"",
    "SaveBeforeActivation": false,
    "Extensions": "TEXT,FOLDER",
    "EditorKeyboardShortcut": null
}

The named placeholders also make it easier to distinguish the current document's folder from the project root. If you're editing docs\guides\publishing.md, you may want a terminal at the project root, not inside docs\guides.

For example, an External Program definition that launches Windows Terminal (wt.exe) can use its starting-directory argument:

-d "{ProjectFolder}"

MM expands the project path, and Windows Terminal uses that path as its working directory. Other tools can use the same placeholder with their own directory options.

The project folder comes from MM's project base-path and marker-file configuration, so it can point above the current document's folder. Quote path placeholders, as in these examples, to handle folders and filenames that contain spaces.

You can reach the definitions through Open... > Edit External Programs... on the document tab's context menu. Existing numeric placeholders are still recognized, so the named versions improve readability without requiring you to rewrite every working command.

Wrapping Up

Although on the surface this release is only a point release, behind the scenes this release is a major update due to the complexities of replacing the internal editor engine from ACE editor to Microsoft's Monaco editor. The reason for this major change is that Monaco is better supported than ACE and includes a number of useful features that are useful to Markdown Monster that were not easily achievable using ACE editor. Many of these features come courtesy of the editor in the box, without any special customizations.

The inline diff editor is the biggest visible addition for reviewing changes. The improved search UI, minimap, and scrollbar markers are smaller conveniences that help while you're actually working in a document. Add the syntax and external-tool improvements, and there's quite a bit here beyond a different editing engine.

You can find builds on the Markdown Monster download page and the full release history in the changelog.

this post was created and published with the Markdown Monster Editor

And yeah, while it's fine to notify users that software loaded from an Internet download can potentially cause harm, it's a pain to users unfamiliar with how SmartScreen works or how you can bypass it to install software, despite the scary warning because they trust the source.

That said - always do your Due Diligence and make sure you trust the vendor and the Web site. If not sure, do your research, check reviews and make sure the software is downloaded from the vendor directly or from a reputable alternate source like a package manager, or a trusted download site.

If you've run into the lovely Blue Windows protected your PC screen when installing software from a Web download:

Figure 1 - A scary SmartScreen dialog when you try to install an application

you know what I mean.

As publisher of small software packages like Markdown Monster, Documentation Monster and West Wind WebSurge I run into this issue every single time I upload a new release for public downloads. These are small vendor software applications and because SmartScreen keys of downloaded files and successful installations, they are very negatively affected by 'scary' SmartScreen popups, scaring off customers when initial versions are posted or updated. If users get scared off they're unlikely to return.

Eventually as reputation of the downloads improves due to successful installations, SmartScreen backs off, but the cycle repeats next time a new version is uploaded. In a couple of words: It sucks!

Working around the Problem

Before I go into why SmartScreen pushes those prompts on users, let me give you the quick fix for SmartScreen in most scenarios, assuming you want to install the software regardless of the warning.

You can do the following:

Figure 2 - You can bypass SmartScreen by clicking the not so obvious More info link.

SmartScreen in most scenarios gives you the option of bypassing the warning and installing anyway:

• Click on the More info Link
• Check and make sure the Installer Signature matches the vendor
• If you're sure you trust the vendor and signature
• Click on the Run anyway button

SmartScreen is meant to prevent you from doing a drive-by install of software by bringing up the blue warning screen, letting you know that you are installing potentially unsafe software.

Fair enough - if you install software directly from the Internet, it's possible to install unsafe software that can do bad things to your computer and installed software.

I don't have an issue with popping up the warning screen, because that's a legitimate concern. The way it's done - well, that's a different story - as that form is one big scare tactic from the blue screen to the lack of information about why you might be careful, and how you should proceed. Instead this window works through obfuscation by seemingly just giving one choice: Don't run.

As you've seen you can bypass, but you should most definitely be careful and check the source.

Make sure you Trust the Vendor!

You want to make absolutely sure you trust the vendor and the site of the software that you're trying to install. Bad things can happen if you install Malware, and there's no vetting process for any software directly downloaded from the Web.

If you use the bypass described above, make sure you are familiar with the vendor or the product and check that the signature of the package matches the vendors contact information.

It's good practice when installing software from an unknown vendor, to check reviews or online discussions around the product to ensure the software is legit and comes from a vendor approved download location! There's a surprising amount of information available to let you know if specific software is problematic. Better safe than sorry!

Better Vetting and Local Installs for Software: Use a Package Manager

One way to have a more secure experience is to install software from the Windows Store (if available) or from a Package Manager like WinGet or Chocolatey. These stores and package manager platforms review software before it's published, run malware checks and run through automated tests that check for successful installations and side effects on the system. This process isn't fool proof - but it's often a lot better than installing a random product from a random Web site.

UniGetUi - A Manager for Windows Store and Package Managers

If you want to install from any of these sources check out UniGetUi, which is a free desktop application that lets you search for, install and update software from a number of different stores and package managers. It's a great one-stop tool that lets you hit all sources in one place.

Package managers have an additional advantage over straight downloaded software in that they typically avoid SmartScreen due to Mark of the Web. Because these managers internally download software rather than pulling it down through a browser, installers are run as local executables that don't have a Mark of the Web that triggers SmartScreen (among other things).

Essentially this means, package managers typically bypasses most of the SmartScreen security flags.

Here are a couple of examples of package managers you can run from the Windows Terminal:

winget install MarkdownMonster
choco install DocumentationMonster

... or you can use UniGetUi if you prefer a GUI application.

All of these package managers and the store include commands to update and list already installed components, which is an additional benefit.

Package Managers provide some basic curation for published packages, doing virus scanning and associating publishers with products consistently and removing packages and publishers that are problematic quickly. Before packages are published there's some pre-validation happening by the provider that provides to at least a base level of security compared to what you get directly downloading software.

For this to work, software publishers of Software have to ensure that their software is published on these package managers and kept up to date. Unlike Windows Store however, the process of publishing to package managers - while not exactly simple - is usually well defined and can be completely automated making it something that is a viable alternative for downloads for publishers. You often find way more software on the package managers than you will find in the Windows Store because of it's restrictive requirements.

In short, if you're not sure about some software you're trying to download, downloading froma package manager is often the best approach.

All of the West Wind product download pages have links for Chocolatey and WinGet installers as alternatives to the direct download. Even so, I'm always surprised that the vast majority of users are installing directly from the download - I guess there's some trust there which is good 😄

If you are a vendor linking the various package managers supported on the download page is a good idea, so users that run into problems with your direct download can try the alternate potentially less intrusive package installs.

Remove Mark-Of-The-Web

Another option is to download installers and explicitly remove the Mark-of-the-Web attached to downloaded binaries and installers.

SmartScreen is triggered among other things by Mark-of-the-Web which indicates that a file was downloaded from the Web. Any file downloaded through a browser interface gets marked and Windows detects this mark changing the security consideration of the file.

The various package managers avoid Mark-of-the-Web by directly downloading package content and locally unpacking thereby bypassing the Mark-of-the-Web and thus usually get around SmartScreen.

You can also remove this mark yourself on any downloaded file that gives you security issues when downloaded off the Web.

Unblock-File -Path '.\MarkdownMonsterSetup.exe'

This removes the Mark-Of-The-Web and likely will not trigger SmartScreen on install, even if the required reputation level has not been achieved.

Mark of the Web is not the only criterion but it's a big contributor for SmartScreen popups especially with new downloads.

Windows Store

Microsoft suggests publishing apps through the Windows Store. Windows Store is a curated platform, and software has to go through a very thorough vetting process. The problem is that this process is both slow and cumbersome and there are a million different rules that have to be followed including some restrictions the software can and can't do in some cases requiring that Windows Store versions have to be dumbed down to be eligible for Store publishing.

Developer and developer adjacent tools in particular have a hard time conforming to all the rules, and the lack of attention by reviewers to real-world concerns in the app publishing process make the Windows Store a time consuming pain in the ass.

I had gone through this process on multiple occasions only to be rejected due to a various shell features that are perfectly adequate for the application and just were rejected outright. Bottom line is that not every product can go into the Windows Store.

I don't have the time or resources to deal with Windows Store deployment, plus for commercial software the model going to the store adds additional complexity and fees again resulting in changes to the application to make the Store work.

In the case of West Wind products the effort is not worth the reward.

SmartScreen Rant

As you can tell I'm not a big fan of SmartScreen. Few people - even users - are. I'm not against warning users of the dangers of installing software from the Web or networks in general. But heavy handely and effectively scaring users into avoiding installing software that they might even trust, is something else. And that's really what SmartScreen does.

The issue I have with SmartScreen and its UI are many:

• It doesn't tell you anything other than "Big Scary Warning, Don't Do it!"
• The Bypass operation is obscured and totally un-obvious
• Conversely at first glance the only option appears to be Don't run
• There's no continuity for the vendor publishing updates -
  the more frequently you publish, the more painful SmartScreen is

How does SmartScreen Work

The actual semantics behind how SmartScreen are not officially disclosed by Microsoft, but based on observation I can make some guesses. At the end of the day SmartScreen is a reputation based system.

When updating Markdown Monster to a new Version and immediately downloading and installing it after the new version is live - I always get a SmartScreen dialog when running the installer. After a few hours - and presumably some users that fought their way past SmartScreen, SmartScreen stops showing up. However, your mileage may vary based on your machine or company security policy.

Things that affect SmartScreen popups:

• Unsigned Binaries and Installers
  Unsigned installer always trigger Windows SmartScreen. If the publisher has not signed their binary that's usually not a good sign, but it's not uncommon for open source tools, and small utilities. Be extra careful with these types of installations and make sure triple sure you trust the publisher. Do your research!

• No or few successful Installations
  SmartScreen is reputation based and as such even a signed binary, that has just been uploaded for download is likely to trigger SmartScreen. As more people download and successfully install the software, SmartScreen stops being so aggressive and allows installation. It appears SmartScreen uses Windows statistics for installations, crashes and uninstalls to determine whether an app is 'stable' and doesn't cause problems.

The problem with the latter Installation counting is that every time an update is shipped, the reputation cycle starts over. There's no continuity over the name of the binary or the certificate used - nothing. Even a vendor like me shipping typically weekly updates of the same software with the same cert for 10 years - same shit each and every time.

For Markdown Monster this is not a huge problem, because the reputation turnaround comes quickly enough due to a fair number of downloads. It also helps that it's geared to a tech savvy audience that presumably knows how to bypass SmartScreen.

However, for a new product like Documentation Monster that is relatively unknown and gets only a few downloads, it may never clear the SmartScreen Reputation hurdle between updates because the download count is low. In the meantime SmartScreen's scary warning ensure that many users may never actually install.

New software with a scary blue screen pop up, is simply not a great recipe for getting new users to try out the software for the first time.

Summary

At the end of the day SmartScreen is just something developers and end users have to put up with. It's frustrating that Microsoft has taken such an aggressive approach with SmartScreen rather than providing a more productive approach of providing a Warning Screen with more information and a clearer way to allow for bypassing the warnings when you are sure you want to install anyway.

But alas here we are...

this post created and published with the Markdown Monster Editor

It's been a while since I've posted some Markdown Monster content, so I thought I'd share a fun feature I recently added to my Markdown Monster editor. In the process I'll highlight a useful library and service that is PlantUML, and how you can add support for it in your own C# code, or use a custom RenderExtension in Markdown Monster or elsewhere to pre-process Markdown for PlantUML diagrams. Although this code discusses a Markdown Monster and custom blog implementation, the code I show is mostly generic and can be used easily with your own .NET code.

I arrived here, because a number of people requested preview rendering support for PlantUML in Markdown Monster. I previously hadn't heard much about PlantUML and so my initial reaction was not to since it's kind of niche. But I got several other requests in short order and so I took a look at how PlantUML integration would work. Turns out it's fairly easy to integrate with minimal external dependencies (unlike Mermaid or nomnoml) as it generates fully self-contained image output.

What is PlantUML

PlantUML is a diagramming tool, and as the name suggests primarily produces UML related diagrams but there are a number of other useful diagrams types you can create as well, including visualizations for JSON, YAML, and RegEx and Deployment, Network, Gannt and MindMap charts. Similar to tools like Mermaid or nomnoml, but more focused and with an easier server based usage model, it allows for embedding of diagrams as png or svg images into your text.

The tool is server based, and it works by sending a markup expression that in return generates image content that can be embedded into an <img src> tag. There are no further dependencies or other libraries - just ready to use images that are embedded into HTML.

All the work with PlantUML happens on the server that converts encoded PlantUML markup into an image. There's a public PlantUML server you can use, or you can also run PlantUML on your own either as a Java Server application or via Docker image. Regardless of mode you're interacting with a very simple HTTP GET API that expects an encoded version of PlantUML markup.

Here's what some of the PlantUML diagrams look like:

Note: markup sample text blocks have an extra space inserted before the ```plantuml code directive for rendering purposes in the post. Remove the the space in your actual Markdown markup.

Use Case

 ```plantuml
@startuml
skinparam monochrome true
left to right direction
User1 --> (Story1)
(Story1) --> (Story2)
(Story2) --> (Story3)
@enduml
```

Sequence Diagram

 ```plantuml
@startuml
participant Participant as Foo
actor       Actor       as Foo1
boundary    Boundary    as Foo2
control     Control     as Foo3
entity      Entity      as Foo4
database    Database    as Foo5
collections Collections as Foo6
queue       Queue       as Foo7
Foo -> Foo1 : To actor 
Foo -> Foo2 : To boundary
Foo -> Foo3 : To control
Foo -> Foo4 : To entity
Foo -> Foo5 : To database
Foo -> Foo6 : To collections
Foo -> Foo7: To queue
@enduml```

 ```plantuml
@startsalt
{
  Just plain text
  [This is my button]
  ()  Unchecked radio
  (X) Checked radio
  []  Unchecked box
  [X] Checked box
  "Enter text here   "
  ^This is a droplist^
}
@endsalt
```

Classes

 ```plantuml
class Customer {
    + Name : string <<get>> <<set>>
    + Age : int <<get>> <<set>>
}
class ClassA {
    + ClassA(users:IList<User>)
}
class ClassB {
    + {static} DefaultUser : User <<get>>
    + Users : IList<User> <<get>>
    + ClassB(users:IList<User>)
}
class "IList`1"<T> {
}
ClassA --> "DefaultUser" User
ClassA --> "Users<User>" "IList<User>"
```

Json

 ```plantuml
@startjson
{
  "firstName": "John",
  "lastName": "Smith",
  "isAlive": true,
  "age": 28,
  "address": {
    "streetAddress": "21 2nd Street",
    "city": "New York",
    "state": "NY",
    "postalCode": "10021-3100"
  },
  "phoneNumbers": [
    {
      "type": "home",
      "number": "212 555-1234"
    },
    {
      "type": "office",
      "number": "646 555-4567"
    }
  ],
  "children": [],
  "spouse": null
}
@endjson
```

The output generated can be in various formats:

• png - Image
• svg - drawing
• txt - ASCII Art (yes!)
• uml - links to the interactive editor on the PlantUML site

Here's what a full Url looks like:

http://www.plantuml.com/plantuml/png/<encodedPlantUmlMarkup>

Markdown and Custom Extensions

My use case is specifically for using PlantUML inside of Markdown text and for live preview and output generation in Markdown Monster and in various Markdown rendering Web applications. As I show at the end of this post - I also need it to render this output on my blog, which currently uses a custom Markdown rendering scheme that doesn't have support for PlantUML, and I'll discuss how to add it there using a similar mechanism to what I'll use for Markdown Monster and which is more generic and something you can plug into your own applications.

Markdown

Markdown is a basic markup language that takes text based markup and turns it into HTML. It has a decent set of markup features tailored to representing common HTML constructs typically used for document based HTML layout. Markdown's most common uses are for articles, blog posts, documentation etc. - basically anything that creates document centric output. Markdown is not a good fit for fancy HTML layout as it lacks native constructs for styling or even CSS classes. Markdown is all about text and content, that can be flowed into existing document templates.

Markdown works great for text scenarios, but even there... the set of features is fixed and somewhat limited. There are a number of non-standard Markdown extension formats that are widely recognized and have in a way created a new standard, like GitHub Flavored Markdown (GFM), custom code blocks with syntax highlighting, annotations, generic attributes, media embedding etc. which all are not part of the base Markdown 'standard', but are widely supported by most platforms.

Markdown Customization

Customization beyond that however is often specific to the platform or tooling. So Mermaid charts and PlantUML diagrams tend to be selectively supported by various platforms so you have to think about where your Markdown will end up. For example, GitHub now supports Mermaid as of late 2022, but it doesn't support PlantUML. GitLab supports both. BitBucket supports Mermaid, but not PlantUML and so on. So even if a tool like Markdown Monster adds support for PlantUML in its previewer and output generation, if it doesn't work on GitHub where your Markdown eventually ends up, it's not terribly useful. If I want to publish to GitLab or my blog which now supports PlantUML, it's very useful.

In short: Know your Target Markdown Platform and ensure it supports the features you are using before committing to adding features that might not work where you deploy your final Markdown to.

Creating PlantUML output

The image Url is a sent to a live PlantUML service that creates images on the fly via HTTP GET requests that contain the PlantUML markup in an encoded and compressed format. The online server is surprisingly fast - fast enough in fact to use it in live previews in Markdown Monster where you can type in the PlantUML code, and immediately see changed output reflected (within Markdown Monster's typing delay) in the HTML preview.

In Markdown Monster, I capture the PlantUML markup with the common Markdown code syntax using ```plantuml as shown above, and then using a MarkdownRenderExtension that transforms any of these ```plantuml code blocks into an image HTML element that replaces the code block at render time.

The embedded PlantUML image that replaces the ```plantuml code block looks like this:

<img src="http://www.PlantUML.com/PlantUML/png/UhzxVt9EOd6nWdDfSKb-...003__mC0"
     alt="diagram">

The Url in this case points to the PlantUML server that's online, and processes requests very quickly but there are some usage limits in place. If you plan to do high volume of requests you might want to run a local server instead so you don't get blocked for excessive volume. The PlantUML server rate blocking limits are more than reasonable for casual use, but if you're using server generated code in a Web application for many users, you might need to look at hosting your own PlantUML server.

PlantUML is an open source Java server application, so you can run the server natively or using a provided Docker image in a container on your own hosted server.

• Getting Started with the PlantUML server

Oddball Encoding

PlantUML works via plain HTTP GET Urls that return a binary PNG or SVG result. The only tricky part about this process is an unconventional Url encoding scheme plus deflate compression to produce the encoding token that is sent in the Url.

I found an existing C# version by Jason Deabill (GitHub) of this encoder that is covered in this blog post and available as a gist:

The code produces just the encoded token, and you then append the base Url to use for an <img> tag which again looks like this:

<img src="http://www.PlantUML.com/PlantUML/png/UhzxVt9EOd6nWdDfSKb-...003__mC0"
     alt="diagram">

Markdown Monster and PlantUML

Over the last year or so several people have requested support for PlantUML and since it's pretty straight forward to get live rendering of a diagram using the PlantUML server, this is a nice feature that could be added to Markdown Monster with minimal effort.

There are other Markdown tools that also have support for PlantUML (including a VS Code addin), and Markdown Monster uses the same syntax using a custom 'code block' syntax that looks like this:

As mentioned the syntax for this looks like this, embedded into Markdown text:

 ```plantuml
@startuml
skinparam monochrome true
left to right direction
User1 --> (Story1)
(Story1) --> (Story2)
(Story2) --> (Story3)
@enduml
```

In order to get this to work in Markdown Monster, it needs to:

• Check for the ```plantuml code block
• Extract the PlantUML code block
• Encode the PlantUML code for the Url
• Create a fully qualified PlantUML Url
• Replace the code block with the image

Since this isn't a native Markdown feature, nor an add-in supported by the MarkDig Markdown Parser that Markdown Monster uses, the easiest way to provide this functionality is to create a MarkdownRenderExtension.

Markdown Monster MarkdownRenderExtensions

Markdown Monster has support for an IMarkdownRenderExtension interface that allows for the original Markdown or rendered HTML to be modified as it passes through the Markdown processing pipeline. You can pre-process the markdown before it is rendered, and post process the HTML after it's been rendered essentially replacing the input and output string, before the final rendered HTML is provided to the Previewer or for output generation to HTML or PDF. A Render Extension is implemented as a class that implements IMarkdownRenderExtension and that is then added to a RenderExtensions collection that is processed on every Markdown parsing request.

In the case of the PlantUML Render Extension the extension parses the inbound Markdown text, and replaces any ```plantuml code blocks with the PlantUML <img> HTML element.

Creating a RenderExtension

MarkdownRenderExtensions generally are pretty simple text parsing affairs - they are meant to look either at the original Markdown pre-rendering or the rendered HTML post rendering, and extract some text and replace it with something else. It's a powerful, but simple tool to extend Markdown rendering process for custom formatting or content transformation, and the PlantUML extension is a perfect example of that as it transforms a PlantUML codeblock into an image.

Markdown Monster ships with several internal render extensions for expanding FontAwesome icons, embedding Mermaid charts, embedding automatic Table of Contents and now for PlantUML diagram transformations. End users of the application can also create their own RenderExtensions by creating a Markdown Monster Addin and adding their own IMarkdownRenderExtension to MarkdownRenderExtensionsManager.Current.RenderExtensions.Add(extension).

It's important to understand that MarkdownRenderExtensions are Markdown Monster specific, so any feature implemented as a MarkdownRenderExtension is not guaranteed to work anywhere else but for MM's output rendering.

However, in the case of the PlantUML Render Extension, MM uses standard PlantUML Markdown syntax that is supported by various Git hosting platforms and tools, so while the render extension is not used by those platforms you get the same render output for PlantUML (as long as the Git hosting/rendering platform supports it). Notably GitHub does not support PlantUML directly, but GitLab does. Other tools that support PlantUML include VS Code and Notepad++ (via addins).

Since this addin ends up being a built-in Render Extension in Markdown Monster, I don't need to create a seperate addin (it's good to be king!), but I'll discuss briefly how to create a MM addin at the end. At this point I'll focus on the Render Extension code itself that showcases how to create the image URL and extract the markup.

The PlantUML MarkdownRenderExtension specifically uses a RegEx expression to find the ```plantuml code blocks and replaces them with <img> elements wrapped into a link that jumps to the PlantUML server to allow interactively editing the markup.

Here's the code:

public class PlantUmlRenderExtension : IMarkdownRenderExtension
{
    private const string StartUmlString = "\n```plantuml";       
    private static readonly Regex plantUmlRegex = new Regex(@"(\n```plantuml[\S\s]).*?([\s\S]```)", RegexOptions.Singleline);
  
    public void BeforeMarkdownRendered(ModifyMarkdownArguments args)
    {
        if (string.IsNullOrEmpty(args.Markdown) ||
            !args.Markdown.Contains(StartUmlString))
            return;

        var markdown = args.Markdown;
        var matches = plantUmlRegex.Matches(markdown);
        foreach(var match in matches)
        {
            var origBlock = match?.ToString();
            var umlBlock = origBlock.TrimStart();
            if (umlBlock.StartsWith("```"))                
                umlBlock = umlBlock.Replace("```plantuml",string.Empty).Trim(' ', '`', '\n', '\r');

            var url = mmApp.Configuration.Markdown.PlantUmlServerUrl + PlantUmlTextEncoding.EncodeUrl(umlBlock);                                
            var html = $"<img src=\"{url}\" alt=\"diagram\" />";

            if (url.Contains("plantuml.com"))
            {
                var linkUrl = url.ReplaceMany(["/svg/", "/png/", "/txt/"], "/uml/");
                if (!string.IsNullOrEmpty(linkUrl))
                    html = $"<a href=\"{linkUrl}\" target=\"_blank\">{html}</a>";
            }

            markdown = markdown.Replace(origBlock, html);
        }
     
        args.Markdown = markdown;
    }

    public void AfterMarkdownRendered(ModifyHtmlAndHeadersArguments args)
    { }

    public void AfterDocumentRendered(ModifyHtmlArguments args)
    { }        
}

Listing 1 - extract PlantUML code blocks and replace with rendered diagram images

This MarkdownRenderExtension implements on the BeforeMarkdownRendered() which receives the original Markdown text as input. The code walks through the Markdown and replaces the ```plantuml code blocks with a raw HTML <img> link. The image then gets rendered instead of the code block in the final output to produce the desired inline diagram.

Creating a Markdown Monster Addin for a MarkdownRenderExtension

Markdown Monster can be extended via Addins and if you want to create your own custom MarkdownRenderExtension in order to preview some custom markup, you can do so via a Markdown Monster addin.

• Creating a Markdown Monster Addin
• Creating a Markdown Monster Markdown Render Extension

In summary creating an addin for .NET 8.0 involves:

dotnet new install MarkdownMonster.AddinProject.Template

# Create a folder for your project and change to it
md \projects\SampleAddin
cd \projects\SampleAddin

# Create the new Project - make sure the name ends in 'Addin'
dotnet new markdownmonsteraddin -n SampleAddin --company "West Wind Technologies"

# Build the project - should create a placeholder addin
dotnet build 

Once you've created the addin you can create a new RenderExtension class in the project:

public class SampleRenderExtension : IMarkdownRenderExtension
{
    // Inject markdown text into the bottom of the document
    public void BeforeMarkdownRendered(ModifyMarkdownArguments args)
    {
        // add some text at the end of the markdown
        args.Markdown += $"\n\n<small>generated by Sample Addin {DateTime.Now.ToString("d")}</small>\n\n";
    }

    // Add Headers for the `<head>` section of the template
    // and optionally modify the rendered Markdown HTML
    public void AfterMarkdownRendered(ModifyHtmlAndHeadersArguments args)
    {
    }

    // update the final HTML that involves HTML that is part of the template
    public void AfterDocumentRendered(ModifyHtmlArguments args)
    {
    }
}

Listing 2 - Creating a customer Render Extension in Markdown Monster

To hook up this SampleRenderExtension, add it to the RenderExtensions collection in the Addin's OnApplicationStart() method:

public override async Task OnApplicationStart()
{
    // ... other generated stuff 
    
    MarkdownRenderExtensionsManager.Current.RenderExtensions.Add(new SampleRenderExtension());
}

Listing 3 - Adding a RenderExtension in a Markdown Monster Addin

And that's all there's to it...

When the project builds, it's automatically built into the Addins folder so it should be locally usable, and you can optionally publish the addin to the Addin repository.

Final Thoughts: Implementing MarkdownRenderExtensions in Markdown for your own Applications

RenderExtension processing like this is easy to implement and it has many uses, but this is a Markdown Monster specific feature. Previewer and output generation works in MM, but - as I just realized, it didn't work on my Blog, which uses custom Markdown rendering and which does not have support for PlantUML. Ooops! 😂

This is the point I highlighted earlier:

Know where your Markdown ends up before committing to using a non-standard feature like PlantUML.

Since my blog is a custom implementation and uses custom Markdown rendering (using a the same engine as MM does, but without the MM specific extension model) I ended up implementing IMarkdownRenderExtension into my custom Markdown renderer. As it turns out that's relatively simple if you have a single point parsing implementation as I do (which incidentally is nearly the same as what I use in Markdown Monster and in Westwind.AspNetCore.Markdown).

I've added it now, and the reason you can see the expanded PlantUML diagrams from the top of the post rendered into the page is because of the new RenderExtension.

In case you want to do something similar in your own apps, here's the implementation and integration of IMarkdownRenderExtension:

public interface IMarkdownRenderExtension
{
    void BeforeMarkdownRendered(ModifyMarkdownArguments args);

    void AfterMarkdownRendered(ModifyHtmlAndHeadersArguments args);

    void AfterDocumentRendered(ModifyHtmlArguments args);

}
// modify original Markdown text
public class ModifyMarkdownArguments
{
    public ModifyMarkdownArguments(string markdown = null, MarkdownDocument doc = null)
    {
        Markdown = markdown;
        MarkdownDocument = doc;
    }

    public string Markdown { get; set; }

    public MarkdownDocument MarkdownDocument { get; }
}

// modify rendered Html text
public class ModifyHtmlAndHeadersArguments
{
    public ModifyHtmlAndHeadersArguments(string html = null, string markdown = null, MarkdownDocument doc = null)
    {
        Html = html;
        Markdown = markdown;
        MarkdownDocument = doc;
    }

    public string Html { get; set; }

    public string Markdown { get; }

    public string HeadersToEmbed { get; set; }

    public MarkdownDocument MarkdownDocument { get; }
}

//  modify final rendered HTML (in template situations)
public class ModifyHtmlArguments
{
    public ModifyHtmlArguments(string html = null, string markdown = null, MarkdownDocument doc = null)
    {
        Html = html;
        Markdown = markdown;
        MarkdownDocument = doc;
    }

    public string Html { get; set; }

    public string Markdown { get; }

    public MarkdownDocument MarkdownDocument { get; }
}

Figure 2 - Implement your own RenderExtensions with pre and post Markdown render processing

The arguments essentially pass in the Markdown or Html properties as string properties that can be modified and are then passed through the render pipeline.

I like to create an application wide MarkdownRenderExtensionsManager with a static Current property so i can globally access and add/remove/manage the applied Render Extensions for the application.

public class MarkdownRenderExtensionsManager
{
    
    /// <summary>
    /// Global application instance of the Extensions Manager
    /// </summary>
    public static MarkdownRenderExtensionsManager Current { get; }

    /// <summary>
    /// Active Render Extensions. You can add your own extensions on application startup
    /// </summary>
    public List<IMarkdownRenderExtension> RenderExtensions { get; set; } = new();

    static MarkdownRenderExtensionsManager()
    {
        Current = new MarkdownRenderExtensionsManager();
        
        // apply default extensions
        Current.RenderExtensions.Add( new PlantUmlRenderExtension() );
        Current.RenderExtensions.Add( new FontAwesomeIconsRenderExtension() );
    }
    
}    

Listing 3 - using a Singleton class via the Current prop to manage application wide Render Extension usage

Next you need to hook the actual pre and post processing into your Markdown parsing pipeline. In my apps I use a Markdown Parser wrapper with a Parse() method where I can apply the MarkdownRenderExtension processing:

public class MarkdownParserMarkdig : IMarkdownParser
{
    public static MarkdownPipeline Pipeline;

    public List<IRenderExtension> RenderExtensions { get; set;  } 

    public MarkdownParserMarkDig() 
    {
            if (Pipeline == null)
            {
                Pipeline = new MarkdownPipelineBuilder()
                //.UsePipeTables()
                //.UseAutoLinks()
                //.UseCitations()
                //.UseEmphasisExtras()
                //.UseDiagrams()
                .UseEmojiAndSmiley()                
                .UseAdvancedExtensions()
                .UseYamlFrontMatter()
                .Build();
            }

            RenderExtensions = new List<IRenderExtension>();
            RenderExtensions.Add(new PlantUmlRenderExtension());
    }
    
    public string Parse(string markdown)
    {
        if (string.IsNullOrEmpty(markdown))
            return string.Empty;
    
        // Markdown RenderExtension Handling
        foreach(var renderExtension in MarkdownRenderExtensionsManager.Current.RenderExtensions)
        {
            var args = new ModifyMarkdownArguments(markdown);
            renderExtension.BeforeMarkdownRendered(args);
            markdown = args.Markdown;
        }
    
        var html = Markdown.ToHtml(markdown, Pipeline);
        html = HtmlUtils.SanitizeHtml(html);
        html = ParseFontAwesomeIcons(html);
    
        // Rendered Html RenderExtension Handling
        foreach (var renderExtension in MarkdownRenderExtensionsManager.Current.RenderExtensions)
        {
            var args = new ModifyHtmlAndHeadersArguments(html, markdown);
            renderExtension.AfterMarkdownRendered(args);
            html = args.Html;
        }
    
        return html;
    }

Listing 4 - Hooking up custom Render Extension processing. Just add additional extensions as needed.

My Markdown parser simply has a Parse() method which in this case calls into Markdig.ToHtml() to render the Markdown to HTML. The class wrapper is used to support multiple classes and also to configure MarkDig and which features of its pipeline you want to use when parsing.

With all of this in place I can now apply any Render Extension like the PlantUML version shown in Listing 1.

A bonus feature in the future might be to build a PlantUML MarkDig extension. When I have some time I might look into that, but it's a bit more work than the simple PlantUmlRenderExtension mechanism shown here. Oh and I think I need to add MarkdownRenderExtension support to my existing Markdown libraries. But I leave that for another day 😄

Resources

• Getting Started with the PlantUML server
• Westwind.AspNetCore.Markdown

this post created and published with the Markdown Monster Editor