Yesterday I added a new feature to my blog application, and now as a user, you can add comment with Markdown syntax. Please try it and let me know if you find any problems.

Before this update, the comment function in JiwhizBlog was a mess. What user entered would be displayed below main blog post as plain text. It looks very ugly because Thymeleaf <th:text> will escape the comment text and browser will render it in one paragraph without format. There are two main reasons that I don't want to use <th:utext>, which is the unescape version. First, Thymeleaf is very strict with the html text, and it will throw exception when there is syntax error in html content. Second and the most important reason, I don't want user to inject any dangerous code into my application. There are many Javascript HTML WYSIWYG or rich text editors, and some are very fancy. However I only need a simple comment input feature, as simple as you are writing an email. So here comes Markdown!

When I use Github Wiki Editor, I like the Markdown edit mode. It is very simple and easy to use. So I did a research about it. Markdown means two things:

(1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.

And there are plenty of Open Source Java implementations for this lightweight markup language. I chose Txtmark, a markdown processor written in Java. It has no dependency, and works with Maven.

I spent less than an hour on adding Txtmark to my project. Just one tiny change in my Java code, adding a new method to CommentPost class:

    public String getHtmlContent(){
        return com.github.rjeschke.txtmark.Processor.process(getContent(),
            Configuration.builder().setSafeMode(true).build());
    }

To my surprise, Txtmark works amazingly good. After updating some page template files (using <th:utext> to display html content of comment after markdown processing), I can see formatted comment displayed in the blog post pages.

Now you can enter comment with Markdown syntax. For example, empty line will break your text into paragraphs. And here is the list of mostly used syntax:

Title

You can use ### Title ### to display a title. Please don't use # or ##, because <H1> and <H2> are too big on the pages. Txtmark doesn't support configurable html tags filtering yet.

Block Quote

Just like in emails, you can use > to indicate a block quote. And it can be nested.

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

The result will be:

This is the first level of quoting.

This is nested blockquote.

Back to the first level.

URL Link

If you want to post a link in the comment, just follow this example:

[an example](http://example.com/ "Title")

The link text is delimited by [square brackets], and the url is inside the parentheses. "Title" is optional.

Code Block

As a programmer, we also want to post our code.

If you just want to wrap a word or a piece of text with <code> tag, wrap it with backtick quotes (`).

To produce a code block, simply indent every line of the block by at least 4 spaces. For example, given this input:

My sample code:

    <span>&copy; JIWHIZ Consulting Inc. 2012-2013. All right reserved.</span>

Will generate html:

<p>My sample code:</p>
<pre><code> <span>&copy; JIWHIZ Consulting Inc. 2012-2013. All right reserved.</span>
</code></pre>

So you don't need to escape any html tags or &, Markdown processor will handle it for you.

Markdown is very powerful, and there are many other syntax features for us to explore. Please try it next time when you want to post a comment in my blog, and your comment will look pretty!