The warning dialog is one thing as it is a valid concern to warn people about installing software from unknown locations. But using provocative colors (blue screen anybody?), scary language and making the step around procedure un-obvious is to essentially scare people out of installing external software, which is a age-old staple of Windows usage.

It's a pain to users who often get scared away from installing software that is legitimate and it's a pain to developers who have to deal with lost users and the support that comes from questions around why the application won't install.

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 not likely 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 it's clearly designed to scare users out of installing apps not coming from the Windows Store.

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 if you download from the Web.

Make sure that if you do use the bypass described above you are familiar with the vendor and 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!

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 platforms review software before it's published, run malware checks and run through automated tests that check for successful installations and side effects. It's not full proof - but you do get at least some vetting of software.

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.

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.

This bypasses most of the SmartScreen security flags. Here are a couple of examples you can run from the Windows Terminal:

winget install MarkdownMonster
choco install DocumentationMonster

All of the managers include commands to update and list already installed components.

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. So there's some pre-validation happening by the provider that provides a better pre-requisite for security than 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. 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.

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 - 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 as users that get SmartScreen'd can use it as an alternative that is likely to work better.

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.

Windows Store

Microsoft suggests publishing apps through the Windows Store. Windows Store is a curated platform, and software has to go through a thourough 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.

But what pisses me off though is that many users are sure they want to install, and perhaps have even installed a previous version of same software from the same site, and they are still warned away the same as everyone else. Often users don't know how to navigate past the scary blue dialog to install - most casual users are simply scared off.

The way that SmartScreen does this seems particularly nasty, clearly trying to scare users into not installing externally downloaded apps, and trying to push people to Windows Store installed apps which never are forced through this rigmarole.

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

Essentially SmartScreen is designed to scare users, without giving any useful information and worse using a limited and flawed algorithm that doesn't take into account actual usage or continuity using forced certificates. At this point it even seems that having an Authenticode Certificate on the installer has no retention value for reputation whatsoever, even or maybe especially when using Microsoft's own Trusted Signing support.

Having no certificate is still worse though, because unsigned installers automatically throw up SmartScreen regardless of reputation.

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.

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

With a heavy heart and a lot of hand wringing, I decided last week to take down the Markdown Monster source code from the public GitHub repository due to rampant license abuses.

The GitHub repository is still there and will continue to be there. You can still download Markdown Monster installers and access the Chocolatey, Snap and WinGet packages. Issues will continue to be processed and fixed and new versions will be forthcoming. Markdown Monster is not dead!

But the source code out in the open is now a thing of the past and only available by explicit request in a private repository.

In this post I'll talk about the reasons for this action as well as offer some of my thoughts on the state of software today. You can take the latter with a grain of salt, but the discussion of the hows and whys of having source code in the open and how it didn't work out for me might be useful to others who are thinking about doing something similar.

A History of Markdown Monster as a Product

Markdown Monster is a Windows based Markdown Editor and Weblog Publisher that provides a ton of functionality around the basic process of Markdown editing. It sounds simple enough, but to do Markdown right and provide a productive workflow for writing, there are a lot of things that you can do to make the process easier and Markdown Monster is my take on doing that. What started as a fairly minimal editor has transformed in a multi-functional application, that still provides a simple user experience while providing many sophisticated addon features. You can check out the features either on the Markdown Monster site or on the GitHub repository.

Markdown Monster started very modestly but has grown both in feature scope as well as popularity.

The project is not and never was a FOSS (Free Open Source) project. But it did have source code on GitHub out in the open, and uses a commercial license that requires a license purchase or use one of several avenues related to supporting the project to get a free license. Free licenses are offered to contributors (both code as well as feedback, help with tracking down bugs, or any other valuable support of Markdown Monster up to our discretion) as well to various developer programs and organizations. Discounted licenses are available depending on international locations.

When I started with Markdown Monster it was a very small project and licensing was mostly an afterthought, but as time went on the product grew in sophistication, and today it is used by more than a thousand people every day on average. Supporting and updating Markdown Monster has become much more than just a small side project that I can work on for a few hours a week between adding new features, fixing bugs and fielding support for issues, feature requests and other minutiae.

From the very beginning I was pretty clear in my vision to not make this a free product. I have plenty of true FOSS open source projects where all code is open and free to use, but when it comes to building what ended up being a commercial product as a one-man shop developer, the effort involved in development and support goes beyond what I can afford to just give away in time and effort, even in light of free competition from other editors that have big corporate backing or from small tools that are much less feature rich.

For me I was never about giving Markdown Monster away for free. If you don't like it - use something else!

Early Days

Initially - before there was a lot more interest - this dual distribution worked out well. Many people registered and played by the licensing rules. The source code got picked up in Forks and there also were a fair amount of small contributions in those early days.

The ratio between usage and registrations was reasonable at first. And thank you to all of you that did register - I really appreciate that, especially in light of all those that didn't later on.

Additionally, at the start at least, there was quite a bit of incoming support with code submissions, lots of feedback and suggestions, or simply working through features or bugs, which resulted in me giving out quite a few free licenses for helping along Markdown Monster to become a better product. I really want to thank those contributors as well - you've all helped make Markdown Monster a much better tool, and I really appreciate all the feedback and discussion. Many have resulted in new and useful features and enhancements that I would not have made on my own.

Over time though, as Markdown Monster has added many more features and the code has gotten more complex, that involvement has died down some, as the product has matured and found it's niche. But there are still many great feature requests and bug reports and that is also much appreciated. And there are still a number of people who frequently provide valuable feedback or other support that warrants free licenses.

I strongly believe in:

Give something, get back something. Value for value!

Whether that's with $$$ or feedback or time or promotion, I believe something should come back for use of software. And I'm not just talking about MM here, but in more general terms and especially for OSS projects.

Popularity and Abuse

But as Markdown Monster became yet more popular and I started looking at the logs it became quite obvious that the vast majority of users were not playing by the rules. The ratio between usage and registrations widened, and it was clear that hacked versions were running on fake registrations.

What sort of abuses am I talking about? Markdown Monster tracks anonymous usage statistics and those usage statistics tell a pretty ugly usage story. Markdown Monster is not a free product despite the fact the source code was available on GitHub.

Here are some numbers from some of the recent logs:

• More than 1000 people use Markdown Monster daily on average
• Of users having used MM more than 50 times - less than 1 in 180 is registered
• Of users having used MM more than 20 times - less than 1 in 400 is registered.
• Lots of first time accesses with 'Registered' status from locations that have never registered

For example, there are tons of users in India, China and Russia that show with registered status. Just checked I have 1 registration from China, none from Russia and 2 from India. Clearly somebody's not playing by the rules.

This despite the fact that some time ago I'd set up options for reduced pricing for international locales to make pricing more in in-line with local income. I've offered reduced pricing for licenses in different locales based on the Big Mac Index which assigns percentage discounts based on the locale by request. I put this program up late last year (8 months ago) - to date I had two requests for the discount and one order from it. IOW, nobody gives a shit... because free is always better than cheap, right?

There are also free license offers for Microsoft MVPs, Microsoft Employees, any company that provides free stuff into the MVP program - which is my way of giving back something to that program and those companies that have provided access to tools and software to me over the years. There's generous use of that and that's fine - that's the way it was designed to be.

What I'm trying to get at here is that I've tried to make licenses accessible and give options to make it fair for both sides.

Give something and get something back.

I get it that some will still think a purchased license is too much because you know this other product is free. Fair enough, use that product if that works for you. But that's usually not how that goes. Instead it's use a hacked version and use the non-free product anyway despite not paying for it.

The very worst of it though, is that running the logs also showed me several different re-branded versions of Markdown Monster running under a different name. These people are so lazy they didn't even bother to remove the logging code.

As with all piracy you can make life miserable for everyone, and still not suppress all piracy, so I was opting for trying to make this work with minimal security and requirements and source code out in the open 😄

I'm not so naive to think that some of this wasn't going to happen. I've sold software throughout my professional life and have seen it all before - the ripped versions, and software keys etc. In most previous cases the lenient registration requirements worked out for the most part - most legit users that used the product beyond the trial periods or basics usually end up registering. However Markdown Monster serves a more general audience than my otherwise more business/corporate oriented software, and the the scale of license abuse in MM was something that I didn't expect. Rampant is the word and it's not an exaggeration in this case.

To be clear, I have no one else but myself to blame. It was a conscious choice to keep it simple and open when I started, being optimistic that users would see the value in that for everybody involved, but I was proven naive to think a different, optimistic outcome was going to come from this.

Thank you to those of you that played by the Rules

To be fair there have been also many registrations to Markdown Monster. Many users did play by the rules. And many people have either contributed, made a valuable feature request, or have taken the time to report a bug and followed through the sometimes time consuming process of tracking down a bug.

I want to thank you and provide a glimmer of hope that maybe I'm not a completely hopeless idealist. I really appreciate the support and those of you that have played by the rules that are a huge incentive to continue working on Markdown Monster and improving it going forward.

Pull it!

So as a result of this abuse, I've been contemplating to tamp down on the rampant license abuse by removing Markdown Monster's source code. Having the source code available makes it just too easy to hack the code, remove the licensing or as some have obviously done, completely re-brand Markdown Monster.

I've been contemplating this move for quite some time. Before actually going ahead with it, I wanted to see what kind of reaction I'd get and started off with this tweet from people that I regularly interact with on Twitter:

I was expecting push back and being talked out of going forward.

Instead, surprisingly I got an earful of feedback and a bunch of co-miseration by other developers who had similar stories with code out in the open. The feedback was mostly along the lines "Yeah that sucks, but do what's right for you", which frankly I did not expect.

If you're interested you can follow the discussion on the tweet - there are a lot of insightful comments on this very long thread.

Going, Going... Gone

After this discussion and some more soul searching I ended up pulling the plug and removing the source code - it's now gone from the main Markdown Monster GitHub repo. The code of course is still there in archives for older versions and that's fine. That ship has long sailed for v1. But going forward the code is no longer out in the open.

Version 2.x which is getting close to release will use a different licensing scheme that ties users and usage to specific keys and source code for that version will not be available. This adds more complexity, both on my end for license management as well as for end users who now have to enter long license keys and have to manage licenses for multiple machines.

Of course, Markdown Monster is a .NET app and .NET can easily be decompiled so code ripping isn't really a solved problem, but at least without source code so readily available there's a bit more of a hurdle than simply re-appropriating the application with a few quick code changes.

Source Code Loss Sucks

It's a real bummer for me to kill the code too, as I have often used Markdown Monster source code as examples for blog posts and articles. Not only does the code removal break a lot of old code links, but it also removes easy issue linking on GitHub and quick back references to source code from the GitHub Issues Tracker. It also makes it harder for those that want to contribute and I'm sorry for that, but if you want to contribute or even just play with the source code you can request access to the now private Markdown Monster Code Repository. The private report allows me more control over who has access and weeds out the riff raff to some degree. It turns out with request access few are interested which is both a blessing and a curse.

Markdown Monster is not Dead!

I want to be very clear here: Although I cut off the source code in the GitHub repository:

Markdown Monster will continue as product just as it did before

This change has very little impact on 99% of you using Markdown Monster. Unless you were one of the very few people using the source code - legitimately or otherwise - this has no impact on you at all.

I will continue to work on Markdown Monster, just as I did before, pushing out frequent updates, responding to issues on GitHub, fixing bugs and updating the various distribution points for Markdown Monster.

If you own a license - thank you I really appreciate your support!!! And your license is still good and continues to work just as it did before and you'll continue to get updates of the current major version for free, just as before.

If you don't own a license, the evaluation version continues to work the same as before too: You'll get the same fully functional version of Markdown Monster with the occasional nag screens and notices and a few features that are not accessible.

Source Code

The only thing that changes as of March 14th, 2020 is that the source code is no longer available in public.

The GitHub repository is still up and continues to serve for issue tracking and as a secondary product landing page that contains download, installation and feature links.

But this repository is now devoid of a Src or MarkdownMonster folder that used to contain the source code.

There are still many forks of Markdown Monster out there but those forks will no longer track the live code going forward which now resides in a private repository.

I would much prefer to build Markdown Monster out in the open, but due to the rampant abuse keeping a public repository simply makes it too easy for the shit heads to abuse their privilege.

And for those that want to work with the Markdown Monster code for internal use, or to help improve Markdown Monster, it's possible to request private access to the GitHub repository. There's more info on the licensing page on how to go about that.

Regretabble

While I hate to do this and it is more work for me, private access at least allows me some control over who has access and if the abuse continues I can easily shut off either individual accounts or if necessary every one. We'll see.

As much as I prefer having things out in the open, it wasn't much of a benefit to have the source available during the 4 years of Markdown Monsters time so far. Early on there were a few strong contributions, but as the product has matured that has fizzled. I'm not surprised as Markdown Monster is not exactly trivial to work on. The source is not the easiest to navigate especially anything that has to do with UI.

I'm not complaining: For MM I actually prefer feature requests that I end up implementing unless it's something altogether out of my realm of capability or desire to build. For maintenance it's usually much easier for me to write the code and maintain it long term and streamline it into the overall Markdown Monster application flow.

But I do really regret having the code not in the open. There are so many benefits of having code available to reference. There are lots of small useful code blocks that I've shared over the years (and many more that I have not) that can be useful to others as well as myself for linking or referencing in posts, articles or other online content.

As always it's a few bad apples spoiling the goodwill for everyone else, but I don't know what other options I have if I want MM to continue as a licensed product.

So here we are. It's been a couple of months now since I pulled the source and there has been an uptick in registrations. The flow of incoming orders is definitely more steady and if v2 is an indication a lot of v1 users feel it's worth upgrading to the newer version as well. Again I appreciate those that do play by the rules.

Some Thoughts the State of Software

I'm really sad that it's come to this. As I mentioned I wasn't blind to the idea that this was going to happen but with the initial release I was trying to be cautiously optimistic that this open but licensed concept could work. And in fact it did for the first 2 years or so before Markdown Monster started getting popular.

I've been doing software sales for a loooong time and there's no denying that the trend of commercial value in software is slowly inching its way toward zero. Open Source has done us no favors in that respect as that perpetuates the idea that you can get something for nothing. Some people end up doing all the work while many more do nothing to support the cause and just take without giving something back. There's no value for value proposition there for most participants.

I think there's a big problem with anything that is free. It is a price distortion, because effectively nothing is free. There's always a price associated with anything to create it or on the flip-side, to use it. The price may be hidden or spread out, or worse yet delayed and to be paid back in hidden benefits that aren't obvious. And without a price the value of the item is often easy to just throw away both from the perspective of the user as well as the developer.

Add to that big vendors giving away sophisticated software for free. Visual Studio, VS Code many other editors and IDEs, lots and lots of tools, libraries etc. Think about all the free stuff that we all use everyday - how much have any of us given back to many of those free tools we use? But there's often a catch. Embedded marketing, data collection, etc. etc. all exacts a price.

I'm not immune to subconsciously leaning toward free software either. Even though I go through my list of tools and libraries occasionally to give back something I never end up going through everything - there's too much of that. It's neither obvious, consistent and too often it just gets forgotten and omitted altogether, if not willfully then accidentally.

Honestly the honor system is a lot of work. As a user who actually honors the unwritten contract you have to try to figure out what the thing you're using is worth. And usually we are very likely to err on the downside would be my guess. It takes some effort to do the right thing, to remember to do this every year or every few years. Did you remember to do your part when it was time? For the developer it's an effort too, because they have to incentivize and advertise that 'feature' and try to convince user to contribute in some way when they can effectively ignore the plea altogether. It's a lot of wasted mental energy by comparison to setting a fixed value for what the software is worth in the first place.

After a while we've all been conditioned that the software we do use should be free or at minimum dirt cheap. How often do we all run around looking for something we need and opt for the often inferior solution just because it is free?

As a result we often end up centralized solutions because all resources pour into only the biggest projects that have support from huge numbers of developers, or from huge corporations that control popular open source projects (Microsoft, Google, Facebook, Amazon etc.) by having paid developers doing full-time work 'open source' project.

For smaller developers open source rarely draws enough resources to subsidize a project either financially or via contributions or support. Instead those are the projects that are usually taken advantage of the most. Too small to be taken serious, and overlooked when it comes to supporting when the time comes to pay up or offer up donations/support for OSS solutions. Again, I'm not immune that problem myself and guilty as charged myself! It's the nature of the beast.

What I'm trying to get at that free is a distortion that changes your relationship with the tools you use. It becomes a throwaway thing both for users and developers. If the tool doesn't work users are bound to walk away instead of helping improve it because the assumption is that it has no value. Move on to the next no value thing.

If the developer gets tired of the tool or finally figures out that he's busting his balls for no pay back, he may just decide to walk away without looking back potentially leaving users hanging. Been there done that a couple of times myself too - not proud but had to do it to keep my sanity.

Putting a price on something makes that a lot harder - first because the developer owes something to those that have spent money, and secondly because the $$$ provide at least some incentive to continue on. The user has invested some $$$ too and wants to get her money's worth. A $$$ price also helps crystallize whether there is real value in a project - if it's not free would people still be willing to use it? With free you often never know if it's because your tools are good, or whether it's just because it's free.

I mention all this in context of Markdown Monster, because it is not a free tool and it has to fight the free stigma. I totally get the aversion to non-free and that's fine. If that's not for you - use something else. But what really flummoxed me with this particular product was that it wasn't shunned, but actively subverted to work around the non-free implementation.

The reality is as a small single developer building a real, licensed product, it is difficult to survive on. Markdown Monster is a not a big project and it plays in an area with quite a bit of competition. But yet it's quite popular and there are a lot of users who use it heavily every day myself included. Even if most users would play by the license rules, it still wouldn't be enough to support even myself as a single developer. But it helps in keeping at it.

I have other things going to support myself, while Markdown Monster is one of many side projects I maintain and work on in rotation. Yet because of the popularity more and more of my time ends up being spent in MM to fix bugs, deal with issues and questions and general support. It it worth it? Financially, not by country mile! If I count up the time I've spent vs. the payout I would barely qualify for US minimum wage. For the joy of building this product? Yeah - MM is probably the best thing I've built in my long career of tools I've created all the way back to the mid-nineties. There's a certain pride in that and quite frankly it's been the most fun project I've worked on in a really long time. As a heavy user of MM I also have a keen interest in making it the best that it can be.

So for now, time marches on. Version 2.x is about to release with some changes in registration and licensing, no source code and I'll find out how it goes. I'm sure the lack of code (even if available by requested access) might drive off some people, but if it ends up driving off people who were never going to play by the licensing rules anyway, then maybe it's not a big loss.

We shall see.

this post created and published with the Markdown Monster Editor