MarkdownKit - Open Source Markdown Parser

I’m pleased to announce as the first post on INN the release of MarkdownKit - a fully cross-platform CommonMark compliant Markdown parser for Xojo.

What does it do?

MarkdownKit essentially does one thing and does it well. It takes as input Markdown as a String and returns HTML. It does this quickly and reliably. It’s 100% compliant with the 0.29 CommonMark specification.

Why might I use it?

Writing in Markdown has become incredibly popular, thanks to sites like GitHub, Ghost and even this forum’s software - Discourse. Perhaps you’d like to write a Markdown editor or you’d like to offer Markdown as a supported text format?

Example usage

Using MarkdownKit is very easy. Everything is contained within a single module named MarkdownKit. Paste or drag the MarkdownKit module into your project and use it like so:

Var md As String = "Some **bold** text and `code`"
Var html As String = MarkdownKit.ToHTML(md)
// `html` now contains: 
// <p>Some <strong>bold</strong> text and <code>code</code></p>

Advanced usage

Out of the box, MarkdownKit supports conversion of Markdown to HTML. However, I’ve designed MarkdownKit in such a way as to make it output-agnostic by giving you access to the abstract syntax tree (AST) created during parsing:

Var ast As New MarkdownKit.Document("Some **bold** text")

// Parsing Markdown is done in two phases. First the block structure is 
// determined and then inlines are parsed.
ast.ParseBlockStructure
ast.ParseInlines

// `ast` now contains the Abstract Syntax Tree and can be manipulated.

Why might you want to access the AST? Well, maybe you want to do something as simple as render every soft linebreak in a document as a hard linebreak. Perhaps you want to output the Markdown source as something other than HTML.

MarkdownKit provides a class interface called IRenderer which must be implemented by any custom renderer you write. The built-in MarkdownKit.HTMLRenderer and MarkdownKit.ASTRenderer classes are examples of renderers which implement this interface. Take a look at their well-documented methods to learn how to write your own renderer.

License

MarkdownKit is provided under the permissive MIT License and is therefore open source and you are free to use it in commercial applications.

Where can I find it?

As with all my open source projects, MarkdownKit has it’s own repository on GitHub.

2 Likes

Thanks for this. I had send the info to Marc Zeedar who was ecstatic. His own implementation (used in the app to submit articles for xDev) was written in 2013 (I think) and started to creak badly, so I’m looking forward to him implementing your parser.

I’ll be especially looking forward to learning from looking at a complete code example (and not just a little fragment) written by someone far better than me :wink:

I didn’t realise Marc had his own home-rolled parser. Fingers crossed mine outperforms his and he gets some benefit from it. I’m pretty darn pleased with it. If you are in contact with him, do let him know about this site.

Flattery will get you everywhere Markus :+1:

An exception of class Xojo.Core.InvalidArgumentException was not handled. The application must shut down.

I downloaded your demo and tried to run it but I got this message. As promised, the application shut down. :slightly_smiling_face:

Perhaps I did not download it “correctly”. GitHub confuses me.

Mac: Mohave
Xojo: 2019 r3.1

Private Sub LoadCSS(dark As Boolean)
// Main CSS.
Dim cssFile As Xojo.IO.FolderItem = Xojo.IO.SpecialFolder.GetResource(“css”).Child( If(dark,“dark.css”, “light.css”))
Dim tin As Xojo.IO.TextInputStream = Xojo.IO.TextInputStream.Open(cssFile, Xojo.Core.TextEncoding.UTF8)
mCSS = tin.ReadAll
tin.Close

// RainbowJS CSS.
cssFile = Xojo.IO.SpecialFolder.GetResource(“css”).Child( If(dark,“rainbow-dark.css”, “rainbow-light.css”))
tin = Xojo.IO.TextInputStream.Open(cssFile, Xojo.Core.TextEncoding.UTF8)
mRainbowCSS = tin.ReadAll
tin.Close

End Sub

Dim cssFile As Xojo.IO.FolderItem = Xojo.IO.SpecialFolder.GetResource(“css”).Child( If(dark,“dark.css”, “light.css”))

This is the line that seems to prompt the appearance of the exception class Xojo.Core…

Well, ignore all the noise. It seems that I did not download it correctly. So I was not getting the expected resources. I redid the download procedure in what I presume is the more appropriate way and things are now working.

Sorry…

No problem. We‘ve all been there …

Glad it’s sorted. Let us know if you have any other issues.