I decided to write this Unofficial Tumblr Theme Guide because I found the official documentation somewhat lacking.
Contents
Blocks and Variables
There are two types of tokens in Tumblr themes: blocks and variables.
Blocks take the form of {block:BLOCK_NAME} and must always be paired with a closing token {/block:BLOCK_NAME}.
A block can be either a loop or a conditional.
A loop block will render its contents once for each item in a set of data. For example, {block:Posts} will be rendered 10 times if there are 10 posts in the current page (or just once if it’s a permalink page).
A conditional block will be rendered if its conditions are satisfied, otherwise it is ignored. For example, {block:PermalinkPage} will only be rendered if the current page is a permalink page.
Variables take the form of {VARIABLE_NAME}. If a variable does not have a value in the current context it is replaced by an empty string. For example the {PhotoURL-500} variable will only be rendered inside the {block:Photo} block.
Variable transformations
By prefixing variables with special transformation keywords, Tumblr will output variables in specialized formats — useful when passing data to Javascript, etc. Tumblr currently supports four transformations:
| Plaintext | Prefix any theme variable with “Plaintext” to output the string with HTML-tags stripped and appropriate characters converted to HTML-entities (so they’re safe to include in HTML attributes, etc.). |
| Javascript | Prefix any theme variable with “JS” to output a Javascript string (wrapped in quotes). |
| Javascript Plaintext | Prefix any theme variable with “JSPlaintext” to output a Javascript string (wrapped in quotes) with HTML-tags stripped and appropriate characters converted to HTML-entities. |
| URLEncoded | Prefix any theme variable with “ URLEncoded” to output a URL encoded string. |
Examples:
Theme options
There are five types of options you can use in your themes: boolean, text, image, color and font. The user will be able to edit the options in their “Appearance” tab when customizing their theme. You only have to add a meta element in your header with the name of the option and a default value.
Text
{text:Flickr Username}
You can also use text variables for boolean blocks:
{block:IfFlickrUsername}
My Flickr username is {text:Flickr Username}.
{/block:IfFlickrUsername}
Image
{image:Logo}
Color
{color:Content Text}
Font
{font:Content Text}
Boolean
{block:IfShowPeopleIFollow}
<h2>Following</h2>
...
{/block:IfShowPeopleIFollow}
{block:IfNotShowPeopleIFollow}
...
{/block:IfNotShowPeopleIFollow}
Static Pages
Tumblr pages have three types: standard layout, custom layout and redirect. There are also some reserved page URLs: archive, mobile, iphone, likes, rss, follow, following, followers, queue, customize, dashboard, messages, drafts, post and more.
Standard layout
Standard layout pages are rendered inside the Text post block ({block:Text}). They don’t have notes, note counts and dates. They have a permalink, title and body. They don’t render the IndexPage and PermalinkPage blocks.
Custom layout
Custom layout pages use their own layout instead of your theme’s regular layout. You can copy your theme’s layout and edit it to add content and change things, or you can use a completely different layout.
Redirect
Redirect pages have no layout, they just forward visitors to a URL of your choice. An HTTP 301 permanent redirect is used to do so.
Theme Tags
Basic variables
| {Title} | Title of your tumblr. (HTML-safe) |
| {Description} | Description of your tumblr. (may include HTML) |
| {MetaDescription} | Description of your tumblr. (HTML-safe) |
| {RSS} | RSS feed URL. |
| {Favicon} | Favicon URL. |
| {PortraitURL-XX} | Portrait photo URL for your blog.
Where XX is the length and width in pixels. You can use: 16, 24, 30, 40, 48, 64, 96, 128 |
Page types
| {block:IndexPage} | Rendered on index pages. This includes the homepage, tag pages, day pages and search pages. |
| {block:PermalinkPage} | Rendered on permalink pages. |
| {block:TagPage} | Rendered on tag pages. |
| {block:DayPage} | Rendered on day pages. |
| {block:SearchPage} | Rendered on search pages. |
| {block:Permalink} | Deprecated
Same as block:PermalinkPage. |
Page variables
Permalink page
| {block:PostTitle} {PostTitle} {/block:PostTitle} |
Rendered on permalink pages. (Useful for displaying the current post’s title in the page title) |
| {block:PostSummary} {PostSummary} {/block:PostSummary} |
Identical to {PostTitle}, but will automatically generate a summary if a title doesn’t exist. |
Tag page
| {Tag} | Name of the tag. |
| {URLSafeTag} | A URL safe version of this tag. |
| {TagURL} | The tag page URL with other posts that share this tag. |
| {TagURLChrono} | The tag page URL with other posts that share this tag in chronological order. |
Search page
| {SearchQuery} | The current search query. |
| {URLSafeSearchQuery} | A URL-safe version of the current search query for use in links and Javascript. |
| {SearchResultCount} | The number of results returned for the current search query. |
| {block:NoSearchResults} | Rendered if no search results were returned for the current search query. |
Post types
Post blocks
| {block:Posts} | This block gets rendered for each post in reverse chronological order. The number of posts that appear per-page can be configured the the Customize area for the blog on the Advanced tab. |
| {block:Text} | Text post |
| {block:Photo} | Photo post |
| {block:Photoset} | Photoset post. (Photo posts become Photosets if you add more than one picture) |
| {block:Video} | Video post |
| {block:Audio} | Audio post |
| {block:Quote} | Quote post |
| {block:Link} | Link post |
| {block:Chat} | Chat post |
| {block:Answer} | Answer post |
| {block:Regular} | Deprecated
Same as block:Text |
Text
| {block:Title} | Rendered if there is a title for this post. |
| {Title} | The title of this post. |
| {Body} | The content of this post. |
Photo
| {PhotoURL-XX} | URL for the photo of this post.
Where XX the max width of the photo. You can use: 500, 400, 250, 100 |
| {block:HighRes} | Rendered if there is high-res photo for this post. |
| {PhotoURL-HighRes} | URL for the high-res photo of this post. Max width and height are 1280 pixels. |
| {PhotoURL-75sq} | URL for a square version the photo of this post. 75-pixels by 75-pixels. |
| {PhotoAlt} | The HTML-safe version of the caption (if one exists) of this post. |
| {LinkURL} | A click-through URL for this photo if set. |
| {LinkOpenTag} | An HTML open anchor-tag including the click-through URL if set. |
| {LinkCloseTag} | A closing anchor-tag output only if a click-through URL is set. |
| {block:Caption} | Rendered if there is a caption for this post. |
| {Caption} | The caption for this post. |
Photoset
| {Photoset-XX} | Embed-code for the photoset.
Where XX the max width of the photoset widget. You can use: 500, 400, 250 |
| {block:Caption} | Rendered if there is a caption for this post. |
| {Caption} | The caption for this post. |
Video
| {Video-XX} | Embed-code for the content of this post.
Where XX the max width of the photoset widget. You can use: 500, 400, 250 |
| {block:Caption} | Rendered if there is a caption for this post. |
| {Caption} | The caption for this post. |
Audio
| {AudioPlayer} | Default audio player. |
| {AudioPlayerCOLOR} | Where COLOR you can use: ‘White’, ‘Grey’ and ‘Black’ |
| {block:ExternalAudio} | Rendered if this post uses an externally hosted MP3. Seems to be rendered for Tumblr-hosted files as well. |
| {ExternalAudioURL} | URL for MP3 file. |
| {RawAudioURL} | URL for MP3 file.. iPhone Themes only. |
| {PlayCount} | The number of times this post has been played. |
| {FormattedPlayCount} | The number of times this post has been played, formatted with commas. (e.g. “12,309″) |
| {PlayCountWithLabel} | The number of times this post has been played, formatted with commas and pluralized label (e.g. “12,309 plays”) |
| {block:AlbumArt} {AlbumArtURL} {/block:AlbumArt} |
Rendered if this audio file’s ID3 info contains album art. |
| {block:Artist} {Artist} {/block:Artist} |
Rendered if this audio file’s ID3 info contains the artist name. |
| {block:Album} {Album} {/block:Album} |
Rendered if this audio file’s ID3 info contains the album title. |
| {block:TrackName} {TrackName} {/block:TrackName} |
Rendered if this audio file’s ID3 info contains the track name. |
| {block:Caption} | Rendered if there is a caption for this post. |
| {Caption} | The caption for this post. |
Quote
| {Quote} | The content of this post. |
| {block:Source} | Rendered if there is a source for this quote. |
| {Source} | The source for this post. (May contain HTML) |
| {Length} | “short”, “medium”, or “long”, depending on the length of the quote. Useful for CSS styling, e.g. different font sizes depending on length. |
Link
| {URL} | The URL of this post. |
| {Name} | The name of this post. Defaults to the URL if no name is entered. |
| {Target} | Should be included inside the A-tags of Link posts. Output target=”_blank” if you’ve enabled “Open links in new window”. |
| {block:Description} | Rendered if there is a description for this post. |
| {Description} | The description for this post. |
Chat
| {block:Title} | Rendered if there is a title for this post. |
| {Title} | The title of this post. |
| {block:Lines} |
Loop Rendered for each line of this post. |
| {Line} | The current line of this chat. |
| {block:Label} | Rendered if a label was extracted for the current line of this post. |
| {Label} | The label (if one was extracted) for the current line of this post. |
| {Name} | The username (if one was extracted) for the current line of this post. |
| {UserNumber} | A unique identifying integer representing the user of the current line of this post. |
| {Alt} | “odd” or “even” for each line of this post. |
Answer
| {Question} | The question for this post. (May contain heavily filtered HTML) |
| {Answer} | The answer for this post. (May contain HTML) |
| {Asker} | Simple HTML text link with the asker’s username and URL, or the plain text string “Anonymous”. |
| {AskerPortraitURL-XX} | Portrait photo URL for the asker. Where XX |
Post variables
| {Permalink} | The permalink for a post. (Example: “http://sample.tumblr.com/post/123″) |
| {ShortURL} | A shorter URL that redirects to this post. (Example: “http://tumblr.com/xpv5qtavm”) |
| {PostID} | The numeric ID for a post. (Example: 1234567) |
| {block:More} | Rendered on index pages for posts with Read More breaks. |
| {block:Post[1-15]} | Rendered for the post at the specified offset. This makes it possible to insert an advertisement or design element in the middle of your posts.
Example: {block:Post5}I’m the fifth post!{/block:Post5} will only be rendered on the fifth post being displayed. |
| {block:Odd} | Rendered for every one of the current pages odd-numbered posts. |
| Rendered for every one of the current pages even-numbered posts. | |
| {block:Even} | Rendered for every one of the current pages even-numbered posts. |
| {TagsAsClasses} | An HTML class-attribute friendly list of the post’s tags. (Example: “humor office new_york_city”)
By default, an HTML friendly version of the source domain of imported posts will be included. (Example: “twitter_com”, “digg_com”, etc.) This may not behave as expected with feeds like Del.icio.us that send their content URLs as their permalinks. The class-attribute “reblog” will be included automatically if the post was reblogged from another post. |
Notes
| {PostNotesURL} | URL for partial HTML containing up to 50 notes. Useful for fetching notes via Javascript. |
| {block:PostNotes} | Rendered on permalink pages if a post has notes. |
| {PostNotes} | Standard HTML output of this post’s notes. Only rendered on permalink pages. |
| {block:NoteCount} | Rendered if a post has notes. |
| {NoteCount} | The number of this post’s notes. |
| {NoteCountWithLabel} | The number of this post’s notes with pluralized label. (e.g. “24 notes”) |
Tags
| {block:HasTags} | Rendered inside {block:Posts} if post has tags. |
| {block:Tags} | Rendered for each of a post’s tags. |
| {Tag} | Name of the tag. |
| {URLSafeTag} | A URL safe version of this tag. |
| {TagURL} | The tag page URL with other posts that share this tag. |
| {TagURLChrono} | The tag page URL with other posts that share this tag in chronological order. |
Dates
| {block:Date} | Rendered everywhere except static pages. |
| {block:NewDayDate} | Rendered for posts that are the first to be listed for a given day. |
| {block:SameDayDate} | Rendered for subsequent posts listed for a given day. |
| {DayOfMonth} | “1″ to “31″ |
| {DayOfMonthWithZero} | “01″ to “31″ |
| {DayOfWeek} | “Monday” through “Sunday” |
| {ShortDayOfWeek} | “Mon” through “Sun” |
| {DayOfWeekNumber} | “1″ through “7″ |
| {DayOfMonthSuffix} | “st”, “nd”, “rd”, “th” |
| {DayOfYear} | “1″ through “365″ |
| {Month} | “January” through “December” |
| {ShortMonth} | “Jan” through “Dec” |
| {MonthNumber} | “1″ through “12″ |
| {MonthNumberWithZero} | “01″ through “12″ |
| {Year} | “2007″ |
| {ShortYear} | “07″ |
| {AmPm} | “am” or “pm” |
| {CapitalAmPm} | “AM” or “PM” |
| {12Hour} | “1″ through “12″ |
| {12HourWithZero} | “01″ through “12″ |
| {24HourWithZero} | “00″ through “23″ |
| {Minutes} | “00″ through “59″ |
| {Seconds} | “00″ through “59″ |
| {Beats} | “000″ through “999″ |
| {Timestamp} | “1172705619″ |
| {24Hour} | “0″ through “23″ |
| {TimeAgo} | A contextual time. (“1 minute ago”, “2 hours ago”, “3 weeks ago”, etc.) |
Reblogs
| {block:RebloggedFrom} | Rendered if a post was reblogged from another post. |
| {ReblogParentName} | The username of the blog this post was reblogged from. |
| {ReblogParentTitle} | The title of the blog this post was reblogged from. |
| {ReblogParentURL} | The URL for the blog this post was reblogged from. |
| {ReblogParentPortraitURL-XX} | Portrait photo URL for the blog this post was reblogged from. Where XX you can use: 128, 96, 64, 48, 40, 30, 24 |
| {block:RebloggedFromReblog} | Rendered if a post was reblogged from another reblog. |
| {ReblogRootName} | The title of the blog this post was created by. |
| {ReblogRootTitle} | The URL for the blog this post was created by. |
| {ReblogRootURL} | The title of the blog this post was created by. |
| {ReblogRootPortraitURL-XX} | Portrait photo URL for the blog this post was created by. Where XX you can use: 128, 96, 64, 48, 40, 30, 24 |
Content Source
| {block:ContentSource} | Rendered if there is a content source for a post. |
| {SourceURL} | The content source URL. |
| {SourceTitle} | Title for the source URL. |
| {block:SourceLogo} | Rendered if there is an image logo for a content source. |
| {block:NoSourceLogo} | Rendered if there is no logo for a content source. |
| {BlackLogoURL} | URL for the logo image. |
| {LogoWidth} | Width of the logo. |
| {LogoHeight} | Height of the logo. |
Pagination
| {block:Pagination} | Rendered if there is a “previous” or “next” page. |
| {block:PreviousPage} | Rendered if there is a “previous” page. |
| {block:NextPage} | Rendered if there is a “next” page. |
| {PreviousPage} | URL for the “previous” page. |
| {NextPage} | URL for the “next” page. |
| {CurrentPage} | Current page number. |
| {TotalPages} | Total page count. |
Jump links
| {block:JumpPagination length=”5″} | Loop for rendering additional pagination links.
Rendered for each page greater than the current page minus one half-length up to current page plus one half-length. |
| {block:CurrentPage} | Rendered when jump link is the current page. |
| {block:JumpPage} | Rendered when jump link is not the current page. |
| {PageNumber} | Page number for jump link. |
| {URL} | URL for jump link. |
Permalink pagination
| {block:PermalinkPagination} | Rendered if there is a “previous” or “next” post. |
| {block:PreviousPost} | Rendered if there is a “previous” post. |
| {block:NextPost} | Rendered if there is a “next” post. |
| {PreviousPost} | URL for the “previous” post. |
| {NextPost} | URL for the “next” post. |
Day pagination
| {block:DayPagination} | Rendered if there is a “previous” or “next” day page. |
| {block:PreviousDayPage} | Rendered if there is a “previous” day page. |
| {block:NextDayPage} | Rendered if there is a “next” day page. |
| {PreviousDayPage} | URL for the “previous” day page. |
| {NextDayPage} | URL for the “next” day page. |
Misc
Group author
| {PostAuthorName} | The username of the author of a post to an additional group blog. |
| {PostAuthorTitle} | The title of the author’s blog for a post to an additional group blog. |
| {PostAuthorURL} | The blog URL for the author of a post to an additional group blog. |
| {PostAuthorPortraitURL-XX} | The portrait photo URL for the author of a post to an additional group blog. Where XX is the size in pixels (square), you can use: 128, 96, 64, 48, 40, 30, 24, 16 |
Group blogs
| {block:GroupMembers} | Rendered if the blog is a public group blog. |
| {block:GroupMember} | Loop
Rendered for each additional public group blog member. |
| {GroupMemberName} | The username of the member’s blog. |
| {GroupMemberTitle} | The title of the member’s blog. |
| {GroupMemberURL} | The URL for the member’s blog. |
| {GroupMemberPortraitURL-XX} | Portrait photo URL for the member.
Where XX is the length and width in pixels. You can use: 16, 24, 30, 40, 48, 64, 96, 128 |
Static pages
| {block:HasPages} | Rendered if you have defined any custom pages. |
| {block:Pages} | Loop
Rendered for each custom page. |
| {URL} | The URL for this page. |
| {Label} | The label for this page. |
Submissions
| {block:SubmissionsEnabled} | Rendered if Submissions are enabled. |
| {SubmitLabel} | The customizable label for the Submit link. |
| {block:AskEnabled} | Rendered if asking questions is enabled. |
| {AskLabel} | The customizable label for the Ask link. |
Following
| {block:Following} | Rendered if you’re following at least one blog. |
| {block:Followed} | Loop
Rendered for each blog you’re following. |
| {FollowedName} | The username of the blog you’re following. |
| {FollowedTitle} | The title of the blog you’re following. |
| {FollowedURL} | The URL for the blog you’re following. |
| {FollowedPortraitURL-XX} | Portrait photo URL for the blog you’re following.
Where XX is the length and width in pixels. You can use: 16, 24, 30, 40, 48, 64, 96, 128 |
Likes
| {block:Likes} | Rendered if you are sharing your likes. |
| {Likes} | Standard HTML output of your likes. |
| {Likes limit=”5″} | Limit the output to 5 likes. Maximum is 10. |
| {Likes width=”200″} | Audio and Video players scaled to 200-pixels wide. Scale images and text with CSS max-width or similar. |
| {Likes summarize=”100″} | Text summarized to 100-characters. Maximum is 250. |
If you’ve enabled Twitter integration in your Tumblr preferences, you can include the /tweets.js Javascript file on your primary blog to display your recent tweets. This file runs the callback function recent_tweets(), sending the Twitter API JSON data as its only parameter.
| {block:Twitter} | Rendered if you have Twitter integration enabled. |
| {TwitterUsername} | Your Twitter username. |
Example:
Language variables
| {lang:About} |
| {lang:All of Tumblr} |
| {lang:Archive} |
| {lang:Back} |
| {lang:Blog comments powered by Disqus 2} |
| {lang:Comments} |
| {lang:Download} |
| {lang:Filed under} |
| {lang:Follow on Tumblr} |
| {lang:Following} |
| {lang:Group members} |
| {lang:Home} |
| {lang:Latest Tweets} |
| {lang:Members} |
| {lang:Mobile} |
| {lang:More} |
| {lang:My blog} |
| {lang:Newer} |
| {lang:Newer posts} |
| {lang:Next day} |
| {lang:Next page} |
| {lang:No search results for SearchQuery 2} |
| {lang:Notes} |
| {lang:Older} |
| {lang:Older posts} |
| {lang:Page CurrentPage of TotalPages} |
| {lang:People I follow} |
| {lang:Permalink} |
| {lang:Plays} |
| {lang:Posted at FormattedTime} |
| {lang:Posted TimeAgo from source} |
| {lang:Posted on DayOfWeek the DayOfMonthWithSuffix of Month Year at FormattedTime} |
| {lang:Posts tagged Tag 2} |
| {lang:Powered by Tumblr} |
| {lang:Powered by Tumblr 2} |
| {lang:Previous} |
| {lang:Previous day} |
| {lang:Random} |
| {lang:Random post} |
| {lang:Reblogged from ReblogParentName 2} |
| {lang:Reblogged TimeAgo from ReblogParentName} |
| {lang:RSS feed} |
| {lang:Search} |
| {lang:Search results for SearchQuery} |
| {lang:SearchResultCount results for SearchQuery 2} |
| {lang:Subscribe} |
| {lang:Tagged} |
| {lang:Tags} |
| {lang:View comments} |
| {lang:View high resolution} |
| {lang:View the discussion thread} |
| {lang:Your search for SearchQuery returned SearchResultCount results 2} |