Introduction to Developing a Custom Tumblr Blog Theme

Tumblr is the fastest growing blog network on the web today. With the ability to quickly reblog any of your followers’ posts it truly revolutionizes the way we interact with a digtial community. Tumblr has taken the popular dashboard feature and expanded it into a personal blog feed.

Amongst the many popular features of the service is the ability to directly customize the look and feel of your page. Each blog has its own theme which is used to give your page its layout and color scheme. There are plenty of free and paid themes to choose from, but it’s much easier and more fun to create your own.

2 Million+ Tumblr Themes, Web Templates & More With Unlimited Downloads

Download thousands of Tumblr themes and templates with a monthly Envato Elements membership. It starts at $16 per month, and gives you unlimited access to a growing library of over 2,000,000 Tumblr themes, templates, fonts, photos, graphics, and more.

Explore Tumblr Themes

In this brief tutorial we’ll be going over the major pieces to any Tumblr theme. The engine is powered using straight HTML/CSS code along with in-text variables for block elements. Basic HTML is all that’s required to really get started and build your own theme.

Understanding Pages

Any Tumblr theme is simply a single page of HTML code with conditional case variables in-between. This basically means all of the page views are separated by case variables in one long document.

So for example all posts from your site will be broken down into categories. These are based on media content such as text, image, video, URL link, etc. These are all different options or views for your blog. Separate options can be activated based on whichever type of page is being requested.


Now these types of conditionals are known as blocks. These are known as case variables which display unique content based on certain conditions. Page variables are single containers which hold dynamic values. For example, a Page Title or RSS feed will change with each blog so these values can be added through variables ({Title} and {RSS} respectively).

Building the Header

The heading is the first piece to any Tumblr theme. It contains all the important details about your blog and which meta options are set. Below is a bit of sample code to use in your header to get started.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
<html xmlns="">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="description" content="{MetaDescription}" />
<meta name="if:Show Search" content="1" />
<meta name="if:Show people I follow" content="0"/>
<link rel="shortcut icon" href="{Favicon}" /> 
<link rel="alternate" type="application/rss+xml" href="{RSS}" />
<link rel="stylesheet" type="text/css" href="" media="all" />
<link rel="stylesheet" type="text/css" href="" media="print" />
<!--&#91;if IE 8&#93;><link rel="stylesheet" type="text/css" href="" media="screen" /><!&#91;endif&#93;-->

The document doesn’t look much different than a standard HTML page. You begin with a DOCTYPE declaration followed by your html and head tags. Inside you may notice two lines of code delineating a block element. The opening {block:IndexPage} is creating a block of code to only display on the index page.

Inside we have a title and meta description which display the {title} variable of your blog. All other pages have a title containing a post content summary labeled {postSummary}. You will find these variables littered throughout themes such as {Favicon} and {RSS} for header placings.


One last bit to notice is how all of my theme’s CSS styles are in external documents. This provides a much quicker way to access data and process DOM actions. Also since Tumblr has to load its own files before loading your theme external styles will expedite the whole process.

Blog Posts

Spend some time examining your document body and building your page structure. With time you should reach your primary content area. Inside here is where all of your blog posts and comments will be listed. This is marked by a {block:Posts} and contains many sub-variables.

Within the Posts block we are checking for the different types of media. There are a lot to go over and they’re all relatively straightforward. I’ve added a list of post block types below:

  • {block:Text}
  • {block:Photo}
  • {block:Photoset}
  • {block:Quote}
  • {block:Link}
  • {block:Chat}
  • {block:Audio}
  • {block:Video}
  • {block:Answer} *for ask messages

These may seem a bit difficult to take in at first. Truthfully the best way to understand is by practicing and building out new Tumblr themes. If you’d like deeper information into each post media check out the official themes docs.

Functional Pagination

Tumblr doesn’t plan to keep all your posts loaded on a single page, that could become very intrusive. Pagination is built into Tumblr’s themeing engine and supports next/previous links for your archive pages.


The first style of pagination guides the user between your older pages. Each page generally stores 7-10 posts, but can be altered to contain more. This type of conditional will work on any page and can display links as long as there are more pages to traverse. Below is an example of this style:

    <li><a href="{PreviousPage}">Previous</a></li>

    <li><a href="{NextPage}">Next</a></li>

This is a very rudimentary example, though it does clearly illustrate the point. This could be placed anywhere in your code to generate a Pagination block of links.

The second option is to offer links between posts. These will show only on individual post pages where a visitor can see your content and responses listed. Whenever there is a post either before or after in the archives you can display nav links.

The code looks exactly the same as above, except with slightly different variable names. The initial block checks for {block:PermalinkPagination} instead of just Pagination. Also all instances of Page are replaced by Post as outlined below.

  • {block:PreviousPost}{/block:PreviousPost}
  • {block:NextPost}{/block:NextPost}
  • {PreviousPost}
  • {NextPost}

JumpPage Nav

There is also a 3rd option for navigation links called jump pages. These offer visitors a list of numerical links pointing each towards a page in your blog archives. The structure is similar to other forms of pagination, though with its own slight changes.


I’ve included another example below for Jump Pagination. The content is a bit more confusing to digest so take time to look over the code. There are no new concepts here since all Tumblr themes are straight HTML and basic variables.

{block:JumpPagination length="5"}
        <span class="currentPage">{PageNumber}</span>

        <a class="jumpPage" href="{URL}">{PageNumber}</a>

The length=”5″ attribute through the first element counts how many links to show. This means our block list will always contain 5 links geared towards a central axis.

To further expand on this theory the only times you’ll see the current page towards an endpoint is at the very start or end of navigating pages. The system works by setting the current page directly in the middle of all Jump Pages. So for example on page 7 of our blog archives we should see links for pages 5-9.

Further Readings

These are some of the most basic intro pieces for developing into Tumblr. Themes are a great way to customize your blog and add in your own pinch of creativity. It’s encouraged to check out Tumblr’s official theme documentation for detailed examples and resources.

Some pages you may potentially be interested reading include likes, following count, search queries, and post notes. For every Tumblr account you are given a free theme by default. Spend some time dissecting their official code to get a better understanding of how Tumblr’s system works and how to manipulate your own customizations.