Introducing a new Markdown View Engine for ASP.NET Core

Introducing a new Markdown View Engine for ASP.NET Core

Jan 01, 2017     Viewed 12834 times 0 Comments
Posted in #Markdown  #ViewEngine 

One of the things that I have been working on has been a new view engine option for ASP.NET Core. ASP.NET Core has always supported the concept of view engines which allow you to use a different template syntax options for your views.

ASP.NET Core shipped with a default view engine that called Razor which is of course is the view engine that knew and love from the previous version of ASP.NET.

The new view engine option I have been working on is using markdown syntax which is become popular last few years, especially for those who are working on GitHub.

What is Markdown?

Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats using a tool by the same name. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor. (Wikipedia)

Compared with Razor Syntax

To illustrate the similarities with Razor syntax let me show you some examples that Scott Gu mentioned them long time back in his blog post Introducing "Razor" - new view engine for ASP.NET.

Hello World Sample with Razor

Building it with Razor Syntax

<h1>Razor Example</h1>

<h3>
    Hello @name, the year is @DateTime.Now.Year
</h3>

<p>
   Checkout <a href="/Product/Details/@productId">this product</a>
</p>

Building it with Markdown Syntax

# Razor Example

### Hello @name, the year is @DateTime.Now.Year

Checkout [this product](/Product/Details/@productId)

Loops and Nested HTML Sample

Building it with Razor Syntax

<ul id="products">

    @foreach(var p in products) {
        <li>@p.Name ($@p.Price)</li>
    }

</ul>

Building it with Markdown Syntax

@foreach (var p in products) {
  - @p.Name: ($@p.Price)
}

If-Blocks and Multi-line Statements

If Statements

Building it with Razor Syntax

@if(products.Count == 0) {
    <p>Sorry - no products in this category<p>
} else {
    <p>We have a products for you!</p>
}

Building it with Markdown Syntax

@if (products.Count == 0) {
Sorry - no products in this category
} else {
We have products for you!
}

Multi-line Statements

Building it with Razor Syntax

@{
    int number = 1;
    string message = "Number is " " + number;
}

<p>Your Message: @message</p>

Building it with Markdown Syntax

@var number = 1
@var message = ""Number is "" + number

Your Message: @message

Integrating Content and Code

Does it break with email addresses and other usages of @ in HTML?

Building it with Razor Syntax

<p>
    Send mail to scottgu@microsoft.com telling him the time: @DateTime.Now.
</p>

Building it with Markdown Syntax

Send mail to scottgu@microsoft.com telling him the time: @DateTime.Now.

Identifying Nested Content

Building it with Razor Syntax

@if (DateTime.Now.Year == 2010) {
    <span>
        if year is 2010 then print this <br/>
        multi-line text block and
        the date: @DateTime.Now
    </span>
}

Building it with Markdown Syntax

@if (DateTime.Now.Year == 2011) {
If the year is 2011 then print this
multi-line text block and
the date: @DateTime.Now
}

Layout/MasterPage Scenarios – The Basics

Simple Layout Example

Building it with Razor Syntax

<!DOCTYPE html>
<html>
    <head>
        <title>Simple Site</title>
    </head>
    <body>

        <div id="header">
            <a href="/">Home</a>
            <a href="/About">About</a>
        </div>

        <div id="body">
            @RenderBody()
        </div>
    <body>
</html>
@{
    LayoutPage = "SiteLayout.cshtml";
}

<h1>About this Site</h1>

<p>
    This is some content that will make up the ""about""
    page of our web-site. We'll use this in conjunction
    with a layout template. The content you are seeing here
    comes from Home.cshtml file.
</p>
<p>
    And obviously I can have code in here too. Here is the
    current date/time: @DateTime.Now
</p>

Building it with Markdown Syntax

<!DOCTYPE html>
<html>
    <head>
        <title>Simple Site</title>
    </head>
    <body>

        <div id="header">
            <a href="/">Home</a>
            <a href="/About">About</a>
        </div>

        <div id="body">
            @Body
        </div>

    </body>
</html>
@Layout SiteLayout

# About this SiteThis is some content that will make up the ""about""

page of our web-site. We'll use this in conjunction
with a layout template. The content you are seeing here
comes from Home.md file.

And obviously I can have code in here too. Here is the
current date/time: @DateTime.Now

Layout/MasterPage Scenarios – Adding Sections Overrides

Coming soon ...

As we have seen before markdown view engine make it easier to write clean views without writing HTML tags, but with the limitation of markdown syntax, we saw that we mix both html and markdown especially in layout pages to wrap up the content pages within <body> and use some styles and scripts, thanks CommonMark.NET that makes my life happy and make such thing possible.

FYI this is just a prototype which is still in development so that is why I quote some of the Razor syntax to add dynamic functionality to the content, but still I'm thinking if Razor-like syntax is better choice - like what we saw in @Body - or we may use handlebars - like {{Body}} - or any other sytax to provider rich functionalities.

You can download the source code for this post from my MarkdownViewEngine repository on GitHub.


Leave a Comment