Creating a template, or modifying an existing template will require an understanding of HTML, CSS and Mustache. Blot will be familiar to those who have worked with templates on other blogging platforms.

The best way to learn how to use Blot's template is to clone an existing template and look at its source. Please don't hestitate to contact me if you have any questions.



Modify an existing template
To modify an existing template, create a new template on the design page and specify the template you wish to clone.



Debugging
If you append the query string ?json=true to a URL on Blot, you can retrieve the view used to render its template. I’d suggest using a browser extension like JSONView to make more sense of it.



Routing
When an HTTP request from one of your readers arrives at your site, Blot follows these steps to work out what to send in response. This process is known as routing.

  1. Check your site's template to see if there is a route which matches the path. If there is, render the template and send the HTML as a response.
  2. Check your site's folder to see if there is a file which matches the path. Send the file as a response if it matches.
  3. Check your site's list of redirects to see if you have set one up for this path.
  4. Serve your template's error page if you have one, or Blot's error page if not.

You can read the source code which defines these steps for a more precise idea of how things work.







Custom metadata
You can specify custom entry metadata: Your post.txt
Author: Eric Blair

# Homage to Catalonia

In the Lenin Barracks in Barcelona, the day before...

Use custom metadata in your template like this:

Posted by {{metadata.author}}


Metadata keys are case insensitive. I’d recommend using conditional blocks to prevent your layout breaking if you don’t consistently specify metadata:
{{#metadata.author}}
  Posted by {{metadata.author}}
{{/metadata.author}}

{{^metadata.author}}
  Posted by the editor
{{/metadata.author}}




Thumbnails
Blot generates four sizes of thumbnails:
  • small which has a width and height under 160px.
  • medium the default, which has a width under 640px.
  • large which has a width and height under 1060px.
  • square which has a width and height of 160px.
Blot will not increase the size of smaller images. The JSON added to each entry looks something like this:
{
    ...
    thumbnail: {
        small: {url: "...", width: 160, height: 103},
        medium: {url: "...", width: 640, height: 411},
        large: {url: "...", width: 1060, height: 681},
        square: {url: "...", width: 160, height: 160 }
    },
    ...
}

You can use them in your template like this:

{{#thumbnail.medium}}
    <img src="{{url}}" width="{{width}}" height="{{height}}">
{{/thumbnail.medium}}

Site variables
Blot uses these variables to render Mustache templates.

The tag… is replaced with…
{{title}} your site’s title
{{#menu}}...{{/menu}} a list containing the links on your site’s menu
{{avatar}} the URL to your site’s avatar
{{siteURL}} the URL to your site’s homepage
{{feedURL}} the URL to your site’s RSS feed
{{cssURL}} the URL to your site’s CSS file
{{scriptURL}} the URL to your site’s JS file
{{sitemapURL}} the URL to your site’s sitemap
{{cacheID}} a unix time stamp for the last change you made to your site
{{timeZone}} your site’s timezone
{{roundAvatar}} true if you’ve indicated your avatar is round, false if not
{{hideDates}} true if you’ve chosen to hide the dates on your site, false if not




Post variables
Note that some of the variables, like {{{html}}} have three handlebars rather than two. Mustache escapes variables with two handlebars.

The tag… is replaced with…
{{id}} Number representing the entry's unique ID
{{date}} Human readable publish date for the entry
{{title}} Title of the entry
{{{titleTag}}} HTML of the entry's title
{{{html}}} HTML of the entry, including the title
{{{body}}} HTML of the entry, excluding the title
{{{teaser}}} HTML of the title and the first few items in the entry. You can specify the end of the teaser by inserting the special tag {{more}} into your blog post's file. Everything before {{more}} will be included in the teaser.
{{{teaserBody}}} {{{teaser}}} without the title.
{{summary}} Text summary of the entry
{{more}} Boolean indicating whether teaser differs from html. This is useful for determining whether or not to show 'read more' links.
{{tags}} List of tags for the entry
{{url}} Relative URL to the entry
{{menu}} "true" if the entry is a page, "false" if not
{{created}} Timestamp
{{updated}} Timestamp




Helper functions
Blot exposes some general purpose functions as Mustache lambdas. Note that you can pass another variable from the view to these functions.


The text inside the tag… is replaced with…
{{#encodeURIComponent}}...{{/encodeURIComponent}} The same text, encoded appropriately for a URI component




Lists
You can uses these variables to render lists of posts

The tag… is replaced with…
{{#all_posts}}...{{/all_posts}} Every post ever published
{{#recent_posts}}...{{/recent_posts}} 25 most recent posts on your site
{{#archives}}...{{/archives}} A list of years, months and the posts published on them
{{#all_tags}}...{{/all_tags}} the URL to your site’s avatar