Announcing Markdown.NET

Posted on November 22, 2004  |  

Posted in Development


I've been debating this in my mind for a while now: How do I allow my readers to submit comments that contain HTML and yet maintain control over the markup? It's easy enough to miss a closing tag and skew the entire page. If you read comments below an older post, A CMS Plugin Wanted, you'll see that this is a pretty complicated issue which has no cut-and-dry answer.

Initially, I decided to go to an extreme and strip all HTML tags except anchors. It was simple and secure: nobody would've injected malicious code with comments to exploit the unfortunate ones using buggy Internet Explorer. A number of people tried to paste some ASP.NET code (which is spaghetti-looking HTML) only to notice that nothing showed up.

Enter Markdown

Last week I turned to Markdown, a project run by John Gruber. In his own words:

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Thus, "Markdown" is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.

Please see Markdown basics and Markdown syntax to get a glimpse of what this is about.

John wrote it in Perl, and Michel Fortin ported it to PHP. A bunch of folks helped out along the way with ideas and testing. It's a truly impressive undertaking.

I started looking around for a .NET port, but couldn't find one, and therefore decided to port it myself. In fact, I ported the PHP implementation because I felt it was closer to C# than Perl. It was a bigger undertaking than I anticipated, partly because C# doesn't allow for some of the jiggery-pokery with regular expressions and I had to use match evaluators right and left. In retrospect, I like how C# handles those cases better because the code turned out a little more readable, IMHO.

Why Bother?

  1. I believe Markdown kills two birds with one stone: it allows you to embed HTML snips and format text outside of them at the same time.
  2. I think Markdown.NET, as I dubbed it, would be of benefit to those who run ASP.NET-based blogs, forums, sites. The component is written in C# and compiled into a .NET assembly.

Help Test Please

John Gruber runs an online Markdown converter. Michel Fortin runs a PHP one. To follow in the footsteps I've made available a Markdown.NET converter in my Tools section.

I will appreciate any help in spreading the word about this project. I also need help testing it. I've done quite a bit of testing but I need more eyes and hands.

If you notice that a Markdown snippet is converted incorrectly, please email it to me and point out what's wrong. If you are a .NET developer and want to pinpoint the problem right in the code, the sources are available (see below).

Source Code

The latest code, ver 0.2 as of November 22, 2004, is available for download.


on November 23, 2004

I'm glad to see an implementation of an existing mini-markup language , not a completely new one.

on November 24, 2004

Nice idea, I was after something like this for my site as I wanted users to be able to save some text in their profile (database). Would it be possible to reverse the function, ie convert it back to non-HTML so it could be re-edited in the browser?

Milan Negovan
on November 24, 2004

David, I don't know of a "reverse" convertor. John Gruber, the author of Markdown, would be the right person to ask.

What you can do is store Markdown text in the database and convert it only when you display it.

on November 25, 2004

Very nice, is there any plans to do a WYSIWYG editor for Markdown?

on November 25, 2004

This is really nice to see. I have been struggling to find ways by which I could include standards-based methods for implementing this in my .Net applications.

I will give it a gander. Thanks and good job!

Milan Negovan
on November 25, 2004

Viet, I wonder if any of the control designers would want to plug it into their controls. There are several .NET rich edit controls around.

on November 26, 2004


I love the concept behind Markdown, and had been planning to create my own .NET version.

My most sincere thanks for making this available, Milan.

on November 26, 2004

How can one use this in an ASP.Net application written in VB? Sorry, I do not know much C#.

Milan Negovan
on November 26, 2004

The source code is there in case you want to see how everything works and help pinpoint bugs (should you find any).

I included a compiled assembly (anrControls.Markdown.NET.dll). All you need to do it add a reference to it in VS.NET and it doesn't matter if you're developing in VB.NET or any other .NET language. That's the good thing about managed code. ;)

on November 29, 2004

Excellent job! I can't wait to get home and get this implemented. I have also been wanting a .NET version of this and had implemented some of the basics, but hadn't had time to finish it, so thanks for saving me a ton of time!!!! Keep up the great work!



on November 29, 2004

Donated :).

Milan Negovan
on November 29, 2004

Thank you for your support. ;)

Stephen Haberman
on December 2, 2004

Re: David, Aaron Swartz wrote an HTML to Markdown tool in Python.

Pete Bevin
on January 3, 2005

Rather than converting back and forth between Markdown and HTML, I prefer to keep the markdown source as-is in the database, and just use HTML for output. That way, authors can always go back and edit the original markdown as they typed it.

on June 15, 2005

Thank you

on August 1, 2005

Excellent work on porting Markdown to C#, but I fail to see how it solves the problem of commenters invalidating your markup by missing a closing tag. If I've missed something, I'd be grateful for an explanation.

Milan Negovan
on August 1, 2005

Kenneth, it doesn't really prevent anyone from missing a closing tag or something like that. Markdown is more of a syntax, which is supposed to make text entry easier (with a little learning curve). To enforce proper HTML formatting Tidy is a better fit.

Speaking of which, there's a Tidy port to .NET now (developed by someone else).

on August 2, 2005

Has anyone modified this to add br where there are line brakes. I have been looking for somthing to do this for ages and this is really good!! Thank you!

Milan Negovan
on August 2, 2005

Shamil, feel free to pitch this idea to the author, John Gruber, or extend the component on your own.

Michael Houston
on September 19, 2005

There seems to be a bug in the email address encoding: if you type, for example, < > in the markdown test tool, and then press generate a couple of times, occasionally you just get scrambled text. It's not actually the same every time...

Joakim Magnussen
on December 30, 2005

I've noticed that also (referring to Michael Houston's comment). And it happens because it randomly changes between returning hexadecimal, decimal and raw. The problem is that while randomly changing between hexadecimal and decimal, the only difference between them is an 'x', for example 'd;' and 'm', who are not the same. The error is on line 1202 and line 1204. And the error is that it doesn't actually convert the character to a hexadecimal value etc. But a very detailed description of solution follows:

Replace the contents of line 1202-1204 with the following line:
return string.Format ("&#x{0:x};", (int)c);

There you go! It couldn't be easier! All you've actually done is to remove the line that inserts "&#(some-number-returning-unexpected-result);", and inserting only "&#x(same-number,-but-now-it-gives-expected-result);".

And finally, a note for the author:
Users can still safely insert the dangerous "SCRIPT" HTML element.

Joakim Magnussen
on December 30, 2005

I forgot to mention that removing that line was only a suggestion. It won't any longer be "10% raw, 45% hex, 45% dec", as the original author suggested. But 10 % raw and 90% hexadecimal should work fine, too.

Milan Negovan
on January 2, 2006

Very cool! Thank you, Joakim, for feedback.

on April 13, 2007

Just found another option for reversing markdown... an XSL stylesheet!

Milan Negovan
on April 14, 2007

Will, good stuff!

Ray Akkanson
on March 20, 2008

I think this is a great tool.

Ray Akkanson

amy neymeyr
on October 23, 2008

As to the question about converting Markdown'd HTML --> Markdown. I had this same issue - unlike Commenter 14 (Pete Bevin) I'd rather store the HTML markup in the db, because otherwise I'd have a whole lot of re-coding to do in our public pages.... but, at the same time, I wanted the Markup syntax to be consistent for staff modifying the text. The solution? There's another Conversion Mode - Stupefy. So, rather than calling: Markdown.MarkdownAndEducate(_myObject.Description, ConversionMode.EducateDefault),

I can call: Markdown.MarkdownAndEducate(_myObject.Description, ConversionMode.Stupefy).

worked for my app.... thanks for the port Milan!

on October 28, 2008

Hello amy

you mentioned you call "MarkdownAndEducate" but this is no method on Milans tool, neither in the sourcecode nor binaries available to download?!

Do you have a custom/advanced version?!
If so, I would be interested in. :)

Thanks in advance

Elliot Taylor
on November 9, 2008

Hi Milan,

I must say that this is a great tool, many thanks!

I know it's been a long time since you last looked at this, but have you considered porting Michel Fortin's "PHP Markdown Extra"?

It offers some great enhancements to the original Markdown.

Milan Negovan
on November 11, 2008

Elliot, it has been a long time, indeed. :) I haven't really touched that code in a while and neither did port the extras.

on November 27, 2008

Nice work Milan! I wrote a [tiny app]( that uses Markdown.NET. It's been working flawlessly.

Milan Negovan
on November 28, 2008

Nicely done! Thank you for heads-up.

Asbjørn Ulsberg
on February 26, 2009

Excellent stuff! I would love to collaborate on this code and improve it. I've made some local changes and would like to contribute them back. Could you put this into github or something similar so it would be possible for me to do this? Thanks!

Milan Negovan
on March 2, 2009

Thank you for heads-up. I haven't thought of managing this as an open-source project or anything like that. If there's someone willing to run with it... ;)

on March 24, 2009

This is too cool! I wanted to be able to make simple web pages to provide "page help" for an application. Now I can store markup text right along side the page in my project which is awesome! Thanks a bunch.

on September 11, 2009

Anyone come across a markup to XAML port yet? I want to dual use markdown for WPF app and Browser without using browser controls in WPF.

Jeff Atwood
on December 27, 2009

Milan was kind enough to grant copyright to me so we could open source the code and invite community participation -- thank you!

Announced here:

If you'd like to contribute, the new project home is