Theme Basics

Liquid Reference

Getting Started

Posthaven themes are built using Liquid HTML templates and with related static asset files and YAML configuration.

Creation and editing of themes is currently only supported using via the posthaven_theme gem on the command line for approved accounts. If you comfortable with the command line and web technologies see the Quick Start to get your development environment up and running.

See Theme Structure to get started with information on the files that make up the theme.

The Liquid Reference documents all the objects, tags and filters available in theme Liquid templates.

Quick Start

Shell commands to get started:

gem install posthaven_theme
git clone
cd minimal-theme
phtheme configure YOUR_API_KEY
# Edit the theme
phtheme upload

You’ll need Ruby and RubyGems installed:

Development Tools


To install (you may need sudo).

gem install posthaven_theme

The posthaven_theme gem provides command line support for developing themes on your computer and uploading the component files to Posthaven. It is currently the sole method of uploading files to Posthaven. See the README for usage.

Example Themes

Existing themes are great starting points for building your own theme.

Theme Structure

Themes are composed of 5 directories:


Use the asset_url filter for asset URLs in templates. E.g. for assets/logo.png:

<img src="{{ 'logo.png' | asset_url }}">

The Assets directory contains all of your theme’s assets (images, stylesheets, JavaScripts, etc.). You can access the URL of your theme assets by using the asset_url command in your layout, templates, or snippets.

Use relative URLs in CSS

E.g., in a file saved as assets/blog.css, to refer an image saved as assets/images/fun.png

body {
  background-image: url("images/fun.png");

The asset files you include in assets/ will all be hosted in together in one directory with the same subdirectory structure maintained, but this will not necessarily be at the root of a domain or on the same domain as your blog. So to refer to an image or font use the CSS url() notation with a path relative to the CSS file.


The Config directory contains configuration files for your theme specified in a YAML files.

Optional Files


In layouts insert the template content via the content_for_layout variable:

<div class="main-content">
  {{ content_for_layout }}

The Layouts directory contains the layout files for your theme. A layout is a Liquid file that defines the wrapper HTML into which your template-specific content will be rendered.

Required Files

Currently there is only one valid layout:


Include snippets in templates or other snippets using the include Liquid tag. Do not include the snippets/ directory or .liquid suffix. For a snippet at snippets/bio.liquid:

<div class="sidebar">
  {% include 'bio' %}

The Snippets directory includes Liquid files that you would like to share across templates or split out for organization. Snippets are completely optional. You don’t need snippets to create a functional theme, but they can aid greatly with code organization and reuse. The name of snippets files is not important; they can be called whatever you’d like and nested in subdirectories. Snippets are included into templates using the include Liquid tag.


The Templates directory includes Liquid files that define the markup for each different page on your Posthaven blog. There are eight different templates. The name of your templates is important. Posthaven will look for the template corresponding to the requested page, and an error will occur if it is not present. For example, requests to your site’s homepage will render the template templates/homepage.liquid.

See below for details about each template.

Required Files

Templates and Objects

Each template has different Liquid objects exposed for template use. See the Liquid objects reference for details about each type of object.

All Templates

The following objects are always available, with the exception of private.liquid (see below).


404.liquid is rendered when there is no content for the current URL. No additional objects are available.


The archive.liquid template renders the archive page containing site search and the archive menu for viewing posts from a particular month. All archive rendering is done client side so the archive object, archive_months tag, and archive_results tag all render as placeholders to be manipulated by Javascript in the browser. See the client side rendering note.


The author.liquid template renders the list of posts by a given author on the blog.


The homepage.liquid renders the main listing of posts for the blog.


page.liquid renders a single page.


page.liquid renders a single post.

Private (optional)

private.liquid renders the password page for private sites. The private template is optional and if omitted a password page styled after the Posthaven dashboard will be rendered.

Due to its nature the private template does the site layout and has a limited set of global objects available. As a result it should contain a full HTML page.

The following are the only objects available:





An example config/theme.yml:

name: An Example Theme!
author: Theme Author
  include_in_settings: false
  default: 10
- id: headline
  label: Headline
  default: My Website
  type: text
- id: primary_color
  label: Primary Color
  default: "#000000"
  type: color
- id: show_sidebar
  label: Show Sidebar?
  default: false
  type: checkbox
- id: heading_font
  label: Heading Font
  type: radio
  default: Helvetica
  - value: Helvetica
    label: Sans Serif
  - value: Georgia
    label: Serif
- id: body_font
  label: Body Font
  type: dropdown
  default: Helvetica
  - value: Helvetica
    label: Sans Serif
  - value: Georgia
    label: Serif

Theme settings are specified via a YAML file.

The file should have the following top level fields:


Posts per page is set to a object with two keys:


You can build user customizability into your theme by defining available user settings. Default values must be provided for each setting. If a user does not customize a particular setting, the default will be used. Settings must all have an id, label and type and id and type must be valid values, otherwise they will be ignored.

The settings key should be set to an array of objects which includes the following keys:

In Liquid templates user settings will be available in global settings object. See Templates and Objects and the Liquid settings object

Settings Types

We current support the following setting types:


An example of config/strings.yml:

  first: Page One
  previous: Newer Posts
  next: Older Posts
  last: Final Page

The config/strings.yml file allows themes to override the text generated internally by Posthaven, e.g. in forms and dates, allowing for copy tweaks and/or localization. Keys are nested by type and any omitted keys will fall back to internal defaults. The posthaven/theme-strings repository on Github contains a file with all the available keys and current defaults.