How to make managed library available to Octopus script?

For better Markdown to HTML conversion I want to use MarkDig library available on NuGet: https://www.nuget.org/packages/Markdig/
What is the right way to make it available to the script intended to run on Octopus Server?

One way would be to download NuGet package, extract the library, copy it to fixed location on the server and let the script find it at that location, but I wonder if Octopus can do better than that.

Please advise!
Konstantin

Hi Konstantine,

One way would be to download NuGet package, extract the library, copy it to fixed location on the server and let the script find it at that location, but I wonder if Octopus can do better than that.

That would be the recommended way.

I remember a couple of days ago you submitted another ticket about problems with our MD to HTML converter. Based on that we shipped a fix in 3.8.6: https://github.com/OctopusDeploy/Issues/issues/3123

So I’m wondering if there’s any other functionality that our converter isn’t exactly doing, that’s forcing you to use Markdig. If there is we’d like to hear about it :slight_smile:

Regards,
Dalmiro

We tried the fix in 3.8.6 and indeed it supports tables better than the previous library which did not support tables at all, but still it is not even on par with Markdown to HTML conversion Octopus does in Javascript for UI.
Attached are two pictures how Markdown formatted Release Notes look like in Octopus UI (nice and very readable) and how it looks in email Octopus sends (much much worse). Those are not the same release notes (just don’t have time to find the matching pair), but I’m sure you get the idea.

Hi Konstantine,

The lack of style in the email table is because it doesn’t have css, while the one in the UI does. All you need to do is add some CSS to the table on the email body like this:

In that example I’m assuming the MD table is in the #{table} variable

Dalmiro

Dalmiro, first of all my usual advice - please document it otherwise it is not discoverable.

But there is another confusing point - your Gist includes full html page with and everything, including .
Octopus email template documentation only shows template as part of the page body, implying than enclosing tags are forced over the template by Octopus somehow. This causes the question how to apply while we only have access to template and not to the full page source.
FrontEnd devs enlightened me that may be used within the as well and that’s what I’m currently trying to do, but some clarification (or even documentation) from your side would be helpful too.

Konstantine - The documentation does a good job explaining that HTML can be used to format emails, and it even provides a small but consistent enough example that shows how to use it. Beyond that point, it is up to the user to fully explore the extent of the HTML language (like using inline css styles).

This causes the question how to apply [style] while we only have access to template and not to the full page source.

The correct way to apply styles is as shown on the gist example. I’m not sure what you mean by we only have access to template and not the full page source. You are in full control of the content of the email body and the way it looks.

To give you another example, I modified the content of the gist to include both the example in our documentation and the markdown table converted to HTML with styles. I also removed the <html> and <head> tags which are not necessary (they were added by the editor I was using) and seemed to be confusing you.

For the example to work, you’ll need to add a MD table to your Release Notes. You can use the below MD table as an example:

| Artist            | Record              | Link                                     |
| ----------------- | ------------------- | ---------------------------------------- |
| **Pixies**        | *Doolittle*         | [Spotify](https://open.spotify.com/album/6ymZBbRSmzAvoSGmwAFoxm) |
| **The Smiths** | *The Smiths* | [Spotify](https://open.spotify.com/album/4FR8Z6TvIsC56NLyNomNRE) |

Ah yes, those and tags indeed confused me, sorry.

I’m glad you updated the gist - this way I would understand it from the first try.

Thank you! Issue closed.

Dalmiro, have you actually tried to add css to email template and make Octopus send those emails? When we do that - emails come out unformatted and when we open them in browser to see HTML source, that CSS style we add in the beginning of email template seems to be missing!

Could it be that something along email sending pipeline sanitizes it out?

Konstantine, yes I tested this on my end before sending you the code bit. Just to be double sure I tested it again in another mail client and it worked:

And this is the step template with the email + css + table I used for testing: https://gist.github.com/Dalmirog/7c7c3f6b1a8cfff1853ffa9bb8b631e3 (again, remember that it gets the table from the release notes)

I’m not skilled in the dark arts of SMTP servers, but I can totally see them sanitizing emails as they arrive. That’ll be a conversation you’d need to have with your SMTP admin.

Regards,
Dalmiro

Attached some screenshots from both email clients where you can see the table with css

Dalmiro, it took us some serious pounding the wall with our heads, but what we discovered by almost random tweaking is that Markdown converter used for emails requires empty line before the table to render it properly! Converter used to display Markdown in Octopus UI does not have that (bug? feature? limitation?) therefore it was completely mind boggling to see how tables are formatted in browser and not formatted in email. Now we go through the final testing and verification.

Hi Konstantine - I’m sorry to hear you had to go through that hard to find bug. Is there any chance you can send me 2 examples:

  • 1 email template with the empty line,thus working properly.

  • 1 template as identical to the above one as possible, but without the empty line. I tried to generate one myself but in my case it always seems to work. I might not be quite understanding where The extra line is supposed to go (missing)

Perhaps there’s something on our end that we can do to fix this so other users don’t have to go through the same thing you did. Your examples will help a lot here :slight_smile:

Regard,
Dalmiro