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 https://github.com/posthaven/minimal-theme.git
cd minimal-theme
phtheme configure YOUR_API_KEY
# Edit the theme
phtheme upload
You’ll need Ruby and RubyGems installed:
- Get your theme API key here.
- Install the
posthaven_theme
gem. - Get an existing theme by cloning it with
git
or downloading it. - Configure posthaven_theme for upload using
phtheme configure
. - Edit the theme files.
- Upload your changes to Posthaven using
phtheme upload
. (Or usephtheme watch
to upload files as you edit theme.’) - To preview your theme, go to the Posthaven Dashboard, click on Settings for a site, then the Theme tab. You’ll see your newly uploaded theme under “Your Themes” and you can click the Preview button to view it live.
- Note that for the example themes SCSS files need to be compiled locally before being uploaded.
Development Tools
posthaven_theme
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.
- Minimal Theme – The minimal theme is intended as a starting point for theme develoment. Is is minimally styled and includes most major theme elements. Download.
- Classic Theme – The original Posthaven theme. Download.
- Lanyon Theme – A port of the great Lanyon theme for Jekyll by Mark Otto.
- Ilun Theme – A simple theme with a dark background.
Theme Structure
Themes are composed of 5 directories:
assets
– static asset filesconfig
– theme configurationlayouts
– layout Liquid templatestemplates
– primary Liquid templatessnippets
– smaller Liquid templates for inclusion and sharing.
assets/
Use the
asset_url
filter for asset URLs in templates. E.g. forassets/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.
Recommended Files
assets/screenshot.png
- If present,assets/screenshot.png
will be displayed as the theme’s screenshot on the Posthaven dashboard. Theme screenshots files should be 1200 x 900 pixels. (Though often displayed smaller, they will always be displayed in a 4:3 ratio.)
Use relative URLs in CSS
E.g., in a file saved as
assets/blog.css
, to refer an image saved asassets/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.
config/
The Config directory contains configuration files for your theme specified in a YAML files.
Recommended Files
config/theme.yml
– Basic theme configuration and user settings definitions.
Optional Files
config/strings.yml
– Overrides for text generated internally by Posthaven (e.g. forms).
layouts/
In layouts insert the template content via the
content_for_layout
variable:
<div class="main-content">
{{ content_for_layout }}
</div>
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:
layouts/theme.liquid
snippets/
Include snippets in templates or other snippets using the
include
Liquid tag. Do not include thesnippets/
directory or.liquid
suffix. For a snippet atsnippets/bio.liquid
:
<div class="sidebar">
{% include 'bio' %}
</div>
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.
templates/
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/missing.liquid
templates/archive.liquid
templates/author.liquid
templates/homepage.liquid
templates/page.liquid
templates/post.liquid
templates/tag.liquid
templates/tags.liquid
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).
meta_tags
– Internally generated HTML<meta>
tags for the current page including for Facebook Open Graph and Twitter Cardsposthaven
– See the posthaven Liquid objectrequest
– See the request Liquid objectsettings
– The user defined settings for the theme, see the settings Liquid object andsettings
configurationsite
– See the site Liquid object
404
404.liquid
is rendered when there is no content for the current URL. No additional objects are available.
Archive
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.
archive
– See the archive Liquid object
Author
The author.liquid
template renders the list of posts by a given author on the blog.
author
– A author Liquid object for the author of the current pageposts
– A posts Liquid object with the author’s posts
Homepage
The homepage.liquid
renders the main listing of posts for the blog.
posts
– A posts Liquid object
Page
page.liquid
renders a single page.
page
– A page Liquid object
Post
page.liquid
renders a single post.
post
– A post Liquid object
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:
posthaven
– See the posthaven Liquid objectrequest
– See the request Liquid objectsettings
– The user defined settings for the theme, see the settings Liquid object andsettings
configuration
Tag
posts
– A posts Liquid object with posts for the current tagtag
– A tag Liquid object for the current tag
Tags
tags
– An array of tag Liquid objects
Configuration
theme.yml
An example
config/theme.yml
:
---
name: An Example Theme!
author: Theme Author
url: http://example.com/themes
posts_per_page:
include_in_settings: false
default: 10
settings:
- 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
options:
- 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:
name
– The theme’s nameauthor
– The theme’s authorurl
– URL for the themeposts_per_page
– See below.settings
– See below.
posts_per_page
Posts per page is set to a object with two keys:
include_in_settings
– A boolean specifying where the user can override the number of posts per page set by the theme designerdefault
– The default number of posts per page. Ifinclude_in_settings
is set to false this will always be the number of posts show pere page.
settings
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:
id
– The id used to access the setting in liquid.label
– The label to show to the user on the Posthaven Dashboard while editing the setting.default
– The default value for the setting if unset by the user. For settings withoptions
this should match the option value.type
– The type of the setting.options
– An array of options objects, each entry an array of the form{"label": "label", "value": "value"}
. See example.
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:
checkbox
color
radio
– The setting definition must includeoptions
.dropdown
– The setting definition must includeoptions
.text
strings.yml
An example of
config/strings.yml
:
---
pagination:
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.