Skip to main content

Building a custom tumblr. theme

Lovell Felix 2 min read

Archive note: the tools and versions have moved on. I have kept this entry because the debugging path and the underlying constraint may still be useful.

To start, open the theme editor: click your blog's name at the top of the Dashboard, click "Customize Appearance," then "Edit HTML" under the theme thumbnail. That gives you the current theme's raw HTML.

Tumblr's templating has two building blocks: variables, which insert dynamic data like your blog's title or description, and blocks, which render a chunk of HTML for a set of data (like your posts) or conditionally (like a "Previous Page" link).

HTML head

The head of the document needs a few of the standard pieces, and Tumblr gives you variables for all of them:

{Title} – The HTML-safe title of your blog
{MetaDescription} – An HTML-safe description of your blog, for the meta tag
{Favicon} – A dynamically generated favicon URL from your portrait photo
{RSS} – The URL to your tumbleblog's RSS feed

Dropped into a page skeleton, they look like this:

<html>
  <head>
    <title>{Title}</title>
    <link rel="shortcut icon" href="{Favicon}" />
    <link rel="alternate" type="application/rss+xml" href="{RSS}" />
    <meta name="description" content="{MetaDescription}" />
  </head>
  <body>
    ...
  </body>
</html>

Blocks

Blocks render a chunk of HTML for a set of data (like your posts), or conditionally, like a "Previous Page" link:

<html>
  <body>
    <ol id="posts">
      {block:Posts}
      <li>...</li>
      {/block:Posts}
    </ol>
  </body>
</html>

Displaying posts

Once the basic variables are in place, the posts block is where the real work happens: it's the area where every post type gets rendered. Inside it, you branch out by post type.

{block:Text}{/block:Text} – Text posts
{block:Photo}{/block:Photo} – Photo posts
{block:Photoset}{/block:Photoset} – Photoset posts
{block:Quote}{/block:Quote} – Quote posts
{block:Link}{/block:Link} – Link posts
{block:Chat}{/block:Chat} – Chat posts
{block:Audio}{/block:Audio} – Audio posts
{block:Video}{/block:Video} – Video posts
{block:Answer}{/block:Answer} – Answer posts

Each post type has its own variables and sub-blocks, but a few (permalink, tags) show up in almost every post:

{Permalink} – The exact URL for a single post
{ShortURL} – The sharing-friendly short URL for a single post
{PostID} – The unique numeric post ID for a single post

{block:Posts}
...
  {block:Text}
  <div>
    {block:Title}
    <h2><a href="{Permalink}">{Title}</a></h2>
    {/block:Title}
    <div>
      {Body}
    </div>
  </div>
  {/block:Text}
...
{/block:Posts}

The full variable reference lives on Tumblr's docs page, and you can fork or download the theme this blog used on GitHub.

About the author

Lovell Felix

Infrastructure and reliability engineer working on Linux platforms, configuration delivery, and deployment safety at fleet scale.

@lovellfelix

More notes