Theme Creation

Table of Contents

1 - Overview
2 - Folders
3 - Master Page (site.master)
4 - Post View (PostView.ascx)
5 - Comment View (CommentView.ascx)
6 - Your Style Sheet(s) (css)
7 - Images and Path Considerations
8 - Site Considerations

1 - Overview

Creating themes with BlogEngine.NET is easy and powerful. (Yes, it is an incredible combination and you get it for free with BlogEngine.NET.) Below is all the information you need to create themes in BlogEngine.NET.

At its simplest level, a BlogEngine.NET theme needs a folder with the name of the theme along with a master page (site.master) and 2 user controls, PostView.ascx to format the view of the post and CommentView.ascx to format the view of the comments. Other files often added include style sheets, images, and additional user controls.

2 - Folders

In the web project, there is a folder called themes. All themes are required to be stored in this folder to be used by your blog. To make a new theme, simply add a new folder under in "themes" with the name you wish to call your theme.

3 - Master Page (site.master)

The site.master page is the master page that is applied to every BlogEngine.NET page. Basically, anything you can do with a standard ASP.NET master page you can do here.

3.1 - Header Considerations

Normally, the header contains lots of links, meta data, and scripts. In BlogEngine.NET most of this is pushed in for you, so you don't have to worry about it.

The average theme will only need a link to a style sheet and the the shortcut icon.

Items pushed in as of version 1.1 include:
  • MicroSummary
  • RSD (Really Simple Discovery (for MetaWeblog API tools)
  • RSS/Atom links
  • Content and Start links
  • Open Search
  • Scripts to javascript resources needed
  • Lots of meta and keyword info.

3.2 - Body Considerations

This is where the action takes place. The main thing you need to put in is a ContentPlaceHolder called "cphBody". BlogEngine.NET is expecting it and uses it for the different page types in the application. Basically, this is where page specific details will be displayed.

<asp:ContentPlaceHolder ID="cphBody" runat="server" />
After the ContentPlaceHolder, everything else is really gravy. You can do whatever you like. Add a nice title bar, a side bar, and footer.

You could hard code everything, but that wouldn't be best. Ideally, you will use the Controls and BlogEngine object properties where appropriate. These are all listed below. For example, you could just type in the name of your blog, but if you use the Blog object property, you can change that later in the admin section and have the changes take effect without a coding change.

3.3 - Controls and Object Properties

Ok, you've finally found the most helpful information on this page.


BlogSettings are the values stored in the setting stored in the admin section of your blog. It is all available here including a lot of stuff you'll never likely use in creating themes. The most commonly used items are listed below.
  • Blog Description/Slogan
    • Code: <%=BlogSettings.Instance.Description %>
    • This is the secondary line of the title as specified in your settings.
  • Blog Name
    • Code: <%=BlogSettings.Instance.Name %>
    • Blog title as specified in your settings.
  • Blog Notification Email Address
    • Code: <%=BlogSettings.Instance.Email%>
    • Email address listed in settings for notification
  • Blog Theme
    • Code: <%=BlogSettings.Instance.Theme%>
    • Name of the Theme being displayed.
  • Blog Version
    • Code: <%=BlogSettings.Instance.Version() %>
    • Version number of the version of BlogEngine.NET you are using.

Below is the list of included controls that can be useful on the site.master page or your own custom user controls.
  • Author List
    • Code: <blog:AuthorList runat="Server" />
    • Shows the authors (or users) on the blog
  • Blog Roll
    • Code: <blog:Blogroll runat="server" />
    • Shows the blogroll control. The admin setting controls the entries and other settings.
  • Category List
    • Code: <blog:CategoryList ShowRssIcon="true" runat="Server" />
    • Shows the category list. There is an optional property to control whether or not the category list shows the RSS links.
  • Month List
    • Code: <blog:MonthList runat="server" />
    • Shows the month and year for previous posts
  • Page List
    • Code: <blog:PageList runat="Server" />
    • Shows the pages you created for your blog. (Pages are not the same as posts.)
  • Post Calendar
    • Code: <blog:PostCalendar runat="Server" NextMonthText=">>" DayNameFormat="FirstTwoLetters" FirstDayOfWeek="monday" PrevMonthText="<<" CssClass="calendar" BorderWidth="0" WeekendDayStyle-CssClass="weekend" OtherMonthDayStyle-CssClass="other" UseAccessibleHeader="true" EnableViewState="false" />
    • A calendar with days highlights that have posts.
  • Recent Comments
    • Code: <blog:RecentComments runat="Server" />
    • Shows most recent comments made.
  • Recent Posts
    • Code: <blog:RecentPosts runat="Server" />
    • Shows the most recent posts made.
  • Search Box
    • <blog:SearchBox ID="SearchBox1" runat="server" />
    • Shows search box (and optional include comments checkbox)
  • Search on Search
    • Code: <blog:SearchOnSearch ID="SearchOnSearch1" runat="server" MaxResults="3" Headline="You searched for" Text="Here are some results for the search term on this website" />
    • Shows headline and search results when your site has been navigated to from a search engine.
  • Tag Cloud
    • Code: <blog:TagCloud runat="Server" />
    • Shows the tag cloud as a unordered list. (Use CSS to control the look and style of the list to make it look like a standard tag cloud.)
Important Links

There are a few pages that are important to note. These are pages that BlogEngine.NET makes available for you.

Archive.aspx is a archive listing of all your blog posts by category.
Contact.aspx is a simple contact form configurable in the admin section of the site.
opml.axd is the OPML file for your blogroll.

Your feed url can be retrieved with the following code:
<%=Utils.FeedUrl %>

3.4 - Code behind Considerations

While the standard BlogEngine.NET themes currently don't use the code behind, it doesn't mean it can't be used.

This is a great place to check what page (or type of page) is being displayed and turn on/off sections of the master page among other things.

4 - Post View (PostView.ascx)

The PostView.ascx is the user control that displays a post. This control is used on the main page to show many post (specified in your settings) and also in the individual post page to show the post by itself.

4.1 - PostView Considerations

You need to show the properties of the post you want to make available. Blog features can come into play here. If you want to use Tags you should display them here, if not, then don't. You need to add the admin links here if you hope to be able to edit and delete posts.

4.2 - Controls and Object Properties

Here is the reference for the PostView page.

Post Object

The Post object is the main place to get data about the post to be viewed.
  • Author
    • Code: <%=Post.Author %>
    • The author/user who wrote the post.
  • Content
    • Code: <%=Post.Content%>
    • The content of your post
  • Creation Date
    • Code: <%=Post.DateCreated.ToString("d. MMMM yyyy HH:mm") %>
    • The date your post was created.
  • Perma Link
    • Code: <%=Post.PermaLink %>
    • The guid based link to your post.
  • Relative Link
    • Code: <%=Post.RelativeLink %>
    • The display friendly link to your post.
  • Title
    • Code: <%=Post.Title %>
    • The title of your post
Utility Links

There are a lot of handy functions to pull the links you will need to make your PostView look good.
  • Admin Options
    • Code: <%=AdminLinks %>
    • Links to Edit and Delete the post (only for logged in users).
  • Categories
    • Code: <%=CategoryLinks(" | ") %>
    • The categories associated with the post.
  • Comment Feed
    • Code: <%=CommentFeed %>
    • A link to the comment feed.
  • Rating
    • Code: <%=Rating %>
    • The rating control.
  • Tags
    • Code: <%=TagLinks(", ") %>
    • The Tag list for the post. Contains the text "Tags: " before the tags display. Will be blank if no tags exist.
Other Helpful Links

It you are interested in linking to email, other sites, or internal pages. These are the links to look at:
  • Comments
<a rel="nofollow" href="<%=Post.RelativeLink %>#comment"><%=Resources.labels.comments %> (<%=Post.Comments.Count %>)</a>
<a rel="nofollow" href="<%=Server.UrlEncode(Post.AbsoluteLink.ToString()) %>&amp;title=<%=Server.UrlEncode(Post.Title) %>"></a>
  • DotNetKicks
<a rel="nofollow" href="<%=Server.UrlEncode(Post.AbsoluteLink.ToString()) %>&amp;title=<%=Server.UrlEncode(Post.Title) %>">Kick it!</a>
  • DZone
<a rel="nofollow" href="<%=Server.UrlEncode(Post.AbsoluteLink.ToString()) %>&amp;title=<%=Server.UrlEncode(Post.Title) %>">DZone it!</a>
  • Email
<a rel="nofollow" href="mailto:?subject=<%=Post.Title %>&amp;body=Thought you might like this: <%=Post.AbsoluteLink.ToString() %>">E-mail</a>

5 - Comment View (CommentView.ascx)

The CommentView.ascx is the user control that displays comments left by users on your site. It is a required part although it is common for most themes to use a standard comment template.

5.1 - CommentView Considerations

You will want to show the most standard comment information as well as be sure to include the admin links for when you are logged in.

The CommentView control must inherit from BlogEngine.Core.Web.Controls.CommentViewBase

5.2 - Post and Comment Object Properties

  • Comment Object*
  • Author
    • Code: <%= Comment.Author %>
    • Entered Name of commenter
  • Comment/Content
    • Code: <%= Comment.Content %>
    • The comment (raw) See ResolveLinks function below.
  • Creation Date
    • Code: <%= Comment.DateCreated.ToString("MMMM d. yyyy HH:mm") %>
    • DateTime stamp of the comment
  • ID
    • Code: <%= Comment.Id %>
    • id of the comment
  • Website
    • Code: <%= Comment.Website %>
    • Website of commenter
  • Resolve Links
    • Code: <%= ResolveLinks(Comment.Content) %>
    • Shows links in the comment (or whatever is passed to it).
  • Display Author with WebLink
    • Code: <%= Comment.Website != null ? "<a href=\"" + Comment.Website + "\">" + Comment.Author + "</a>" : Comment.Author %>
    • A clean method for displaying author information
  • Gravatar Image
    • Code: <%= Gravatar(80)%>
    • Displays gravatar image
  • Flag (of commenter)
    • Code: <%= Flag %>
    • Shows flag image and text.
  • Admin Links
    • Code: <%= AdminLinks %>
    • Show Admin links for comment.
  • Reply To Comment
    • Code: <%= ReplyToLink %>
    • Show "Reply" link if Nested Comments are supported and enabled (see Nested Comments below)

5.3 - Nested Comments

BlogEngine.NET version 1.5 introduced nested comments! This allows a visitor on the blog to leave a comment addressing another person's comment. There's only three requirements to have this functionality.

1. The "Enable nested comments" checkbox on the Settings tab in the control panel must be checked.

2. The theme must have two pieces of markup in its CommentView.ascx file.

<%= ReplyToLink %>
A good place to insert this ReplyToLink markup is under the comment where the other footer links are located (Flag, AdminLinks, etc). When nested comments are supported and enabled, the ReplyToLink markup above will render a "Reply" link for each comment. When the "Reply" link for a comment is clicked, this tells BlogEngine the visitor wants to reply to this comment. Additionally, when the "Reply" link is clicked, the comment form and input fields (name, email, website, message, etc) will be re-positioned below the comment the visitor wants to reply to.

The other required markup in CommentView.ascx follows:
<div class="comment-replies"
     id="replies_<%=Comment.Id %>"
     <%= (Comment.Comments.Count == 0) ? " style=\"display:none;\"" : "" %>>
    <asp:PlaceHolder ID="phSubComments" runat="server" />
You would want to place the above markup towards the bottom of CommentView.ascx -- so the nested comments are displayed after the comment being replied to.

Additionally, for the markup above, it's important the placeholder has an ID of phSubComments, the DIV has a class of comment-replies and the DIV is given the exact ID shown above.

3. CSS styles in the style.css file.

CSS styles for nested comments should be added in the theme's style.css file. In the Standard theme, the CSS defined for the comment-replies class on the DIV shown above (and related nested comments CSS) is defined as:
.comment-replies {
    background: transparent url(../../pics/reply-arrow.gif) no-repeat 2px 2px;
    padding: 0 0 0 15px;
    margin: 5px 0 0 0;
#commentlist #comment-form {
    border: solid 1px #ccc;
    background: #fff;
    padding: 10px;
    margin: 10px 0;
You may of course define your own custom comment-replies CSS class in your theme's style.css file. The one shown above is designed to visually indicate the nested comment(s) are in reply to a parent comment.

6 - Your Style Sheet(s) (css)

A style sheet is not a required part of a theme but it is recommended. The goal of this wiki is not to go into the pro/cons of using CSS for your theme creation so we won't go beyond that here.

You may have multiple style sheets with your theme and use them as you see fit.

7 - Images and Path Considerations

Images are recommended. The only thing to remember is the path to theme. If you are linking to an image inside your theme, you will need to give it the appropriate path (with theme folder) so the image can be found.

8 - Site Considerations

Once you have all the pieces put together, it is a good idea to spend some time looking at the different pages to making sure it all looks as you'd hope it would.

Also, it is wise to check the view from as many different web browsers as you deem necessary for your audience.

8.1 - Default View (default.aspx)

This is the page that will display on the home page.
  • How does it look with a full compliment of posts?
  • How does it format with long titles?
  • Do long URLs in posts wrap or break correctly (if your users aren't the most HTML-savvy)?
  • Remember anything that is controled by the settings, can be variable length down the road.

8.2 - Post View (post.aspx)

This is the individual post page.
  • How does it look with long titles?
  • Have you checked short posts and long posts?
  • Be sure to check no comments, a few comments and lots of comment options.
  • Is the "Add Comment" section formatted correctly?
  • Is the "Related Posts" displayed and formated correctly if it is? (What would it look like later with it added/removed?)
  • Is the Comment Form formated correctly?
  • The Comment Form has validation in it. Does it look ok when activated?

8.3 - Page View (page.aspx)

This is only applicable if you have pages on your site.

8.4 - Archive View (archive.aspx)

This is a separate page which can be linked to show post history by category. You'll want to make sure it is formatted nicely.

8.5 - Contact Page (contact.aspx)

The contact page is another page that is easy to forget to check. Make sure it looks good with your formatting.

Last edited Apr 5, 2009 at 7:29 AM by BenAmada, version 4


warenben Jul 6, 2013 at 7:30 AM 
Hello Dear... I am looking for this type of information, and i found it on your blog Thank you.

<a href="">OVDP</a>

mikefulton Dec 17, 2012 at 1:14 AM 
Is anybody even paying attention to this? Why are there a bunch of spam messages that have been around for months or even years...

This page is a good outline for the REAL documentation you're still planning to write someday. The current version is not nearly detailed enough and lacks sufficient examples.

siamkhan Nov 18, 2012 at 5:43 AM 
This is really a good replacement of WordPress , personally I don't like PHP platform because of security and user friendly issues, When I come to know about BlogEngine I am amazed that this engine is a complete replacement of Wordpress.

Can you please add some usefull widgets like CRM, Forms, auto publish blogs to Facebook, Twitter etc, so it will become more powerfull.

1 thing I need to ask, if I want to use master file code behind do I need to use BlogEngine source files and compile it using Visual Studio or there is another way to use code behind ...

Thanks to make life easier ....

Agnesaa May 7, 2012 at 12:09 AM tera gold in our good-quality company is much better than Tera Money may meet your need. You can get gold from us enjoyably, cheapest tera gold hat really makes TERA Online so special? Now, in order to meet plenty TERA game player’s needs, buy tera gold online store Swagvault is about to apply cheap TERA gold with security guarantee as before.

Agnesaa May 7, 2012 at 12:07 AM 
<a href="">tera gold</a>in our good-quality company is much better than Tera Money may meet your need.<a href="">cheapest tera gold</a>You can get gold from us enjoyably, hat really makes TERA Online so special?<a href="">buy tera gold</a> Now, in order to meet plenty TERA game player’s needs, online store Swagvault is about to apply cheap TERA gold with security guarantee as before.

You can get gold from us enjoyably, hat really makes TERA Online so special? Now, in order to meet plenty TERA game player’s needs, online store Swagvault is about to apply cheap TERA gold with security guarantee as before.

adolfina Jan 18, 2012 at 6:39 AM 
What a wonderful article? but I am not that much familiar with this coding information. Now only I have read to gather some knowledge. Thanks for sharing and now I am going to learn about it. Register domain name (

marvenniffi Jul 20, 2011 at 12:48 PM 
I like it so much , Its very interesting and useful for all. [url=] custom logo design[/url]

sharathshetty431 Jun 21, 2011 at 7:02 AM 
actually another one i wanted to ask u was suppose if i have a page called contact.aspx which needs to be linked to the dynamically added contact page .how it must b done.

sharathshetty431 Jun 21, 2011 at 7:02 AM 
actually another one i wanted to ask u was suppose if i have a page called contact.aspx which needs to be linked to the dynamically added contact page .how it must b done.

CSerpent Feb 9, 2011 at 2:29 PM 
Could someone expand, or expand on, section 3.4 - Code Behind Considerations?
I want to have my home page NOT use the master page at all. OR, I want to turn off sections of the master page, as mentioned in 3.4, but really need an example. Thanks in advance!

ferahl Feb 3, 2011 at 9:50 AM 
Great article, after looking at the nightmarish templating systems of others like drupal this feels like a fresh breeze

mollychen08 Oct 28, 2010 at 5:55 AM 
thank you for the share,<a href="">snow boots </a>

aspnet Oct 8, 2010 at 10:42 AM 
I dont understand the step 8.3
I need to change the page.aspx look, add some elements.
How to customize it ?
including page.aspx in my template folder does not work.
Should I change the page.aspx in root folder?

gltriver Sep 3, 2010 at 7:12 AM 
different web browsers as you deem necessary for your audience

rtpHarry Apr 6, 2010 at 10:47 AM 
Minor typo spotted but this wiki doesnt seem to let me edit it. Section 3.1. Repeated use of the word the in "The average theme will only need a link to a style sheet and the **the** shortcut icon."

theluk Jul 7, 2009 at 10:43 PM 
why you recommend Here to use in a masterpage own list of widgets (Controls, right side)? Then there is no possibility to drag them and edit them in admin, right?