Templates

Themes are comprised of a series of templates that tell Postleaf how to render each page. Some templates are required, while others are optional.

Each template is rendered with a certain set of data called the template schema. For example, a post template will have access to a post object that contains information about the target post. Similarly, an author template will have access to an author object and a posts object that contains a list of the target author's post.

The template schema for each template varies. They're described in detail below. Note that globals are made available to all templates.

Properties for objects such as posts, authors, and tags are omitted from the schema for clarity. To learn what properties various objects have, refer to the Objects section below.

Required Templates

These templates are required to build a well-formed Postleaf theme.

author.dust

Renders an author page with the following schema:

  • author – the target author object
  • posts – a collection of post objects by the target author
  • pagination – pagination data for the target author's posts
  • meta – a collection of metadata for the current page

blog.dust

Renders the blog index with the following schema:

  • posts – a collection of posts
  • pagination – pagination data for the current collection of posts
  • meta – a collection of metadata for the current page

default.dust

The default layout Postleaf will use to render templates. Using a layout isn't technically required, but it's strongly recommended as a best practice. See the default theme's layout for an example of what this file will look like.

This template doesn't have its own schema. Instead, the schema is inherited from whatever template is using it.

post.dust

Renders a post with the following schema:

  • post – the target post
  • meta – a collection of metadata for the current page

This template must contain one {@title editable="true"/} helper and one {@content editable="true"/} helper that tells Postleaf which elements will be editable in the editor.

Postleaf outputs semantic markup. It doesn't produce inline styles, so for image alignment, embeds, and embed cards, your theme will need to have some boilerplate styles. See Post Styles section for details.

search.dust

Renders a search page with the following schema:

  • query – the search query used, if any
  • posts – a collection of posts that match the search query
  • pagination – pagination data for the current collection of posts
  • meta – a collection of metadata for the current page

tag.dust

Renders a tag page with the following schema:

  • tag – the target tag
  • posts – a collection of posts that have the target tag
  • pagination – pagination data for the current collection of posts
  • meta – a collection of metadata for the current page

Optional Templates

The following templates are optional. If omitted, Postleaf will use a system template instead.

application_error.dust

Renders the application error page with the following schema:

  • title – a title to display to the user
  • message – a message to display to the user

This error occurs when something unexpected happens, such as a critical error or an error that wasn't properly handled. Note that, in production environments, error details are suppressed for security reasons. Also known as a 500 HTTP error.

not_allowed.dust

Renders the not allowed error page with the following schema:

  • title – a title to display to the user
  • message – a message to display to the user

This error occurs when a request reaches a valid endpoint, but using an unsupported method (e.g. POST instead of GET). Also known as a 405 HTTP error.

not_found.dust

Renders the not found error page with the following schema:

  • title – a title to display to the user
  • message – a message to display to the user

This error occurs when a user requests a page that doesn't exist. Also known as a 404 HTTP error.

robots.dust

Postleaf serves a simple robots.txt file by default. If you to use a custom robots.txt file, you can include a template called robots.dust to replace it.

sitemap.dust

Postleaf serves a basic sitemap.xml file by default. If you want to use a custom sitemap.xml file, you can include a template called sitemap.dust to replace it.

This template is rendered with the following schema:

  • homepage – limited info about the homepage
  • posts – a limited collection of all posts
  • pages – a limited collection of all pages
  • authors – a limited collection of all authors
  • tags – a limited collection of all tags

Data passed to this template is limited for performance reasons, since the sitemap requires Postleaf to fetch all posts, tags, and authors at once.

zen_mode.dust

Postleaf's editor has a feature called Zen Mode that removes everything except the toolbar and your content. It removes distractions and provides a way for writers to focus better.

You can create your own Zen Mode template by creating zen_mode.dust. This template is rendered with the same schema as post.dust. Take a look at the default template for Zen Mode for an example.

Objects

Template schemas usually contain one or more of the following objects. The properties are listed below, and are the same for all objects mentioned in the schemas above.

  • author
    • id – the author's id
    • name – the author's name
    • email – the author's email
    • username – the author's username
    • role – the author's role
    • avatar – the path to the author's avatar image
    • image – the path to the author's cover image
    • location – the author's location
    • bio – the author's bio as a Markdown string
    • website – the author's website
    • createdAt – the date the author's account was created
    • updatedAt – the date the author was last updated
  • meta
    • title – the current page's meta title
    • description – the current page's meta description
  • post
    • id – the post's id
    • slug – the post's slug
    • publishedAt – the date the post was published
    • title – the post's title
    • content – the post's content as an HTML string
    • image – the path to the post's meta image
    • metaTitle – the post's meta title
    • metaDescription – the post's meta description
    • template – the template used by the post
    • status – the post's status (draft, pending, rejected, or published)
    • isPage – set to 1 if the post is a page
    • isFeatured – set to 1 if the post is featured
    • isSticky – set to 1 if the post is sticky
    • createdAt – the date the post was created
    • updatedAt – the date the post was last updated
    • author – the post's author (object)
  • tag
    • id – the tag's id
    • slug – the tag's slug
    • name – the tag's name
    • description – the tag's description
    • image – the path to the tag's cover image
    • metaTitle – the tag's meta title
    • metaDescription – the tag's meta description
    • createdAt – the date the tag was created
    • updatedAt – the date the tag was last updated
  • pagination
    • totalItems – The total number of items in the collection
    • itemsPerPage – The number of items per page
    • currentPage – The current page
    • totalPages – The total number of pages
    • nextPage – The next page number
    • nextPageUrl – the full URL of the next page (no need to use {@url/})
    • prevPage – The previous page number
    • prevPageUrl – the full URL of the previous page (no need to use {@url/}