Skip to content
Reference

Theme data

The data a .hbs theme receives on each page, in the shapes Ghost themes already read.

A Kōlea theme is a folder of Handlebars templates written the way Ghost themes are: the same file names, helper names, and data shapes, so many Ghost themes install as they are. This page lists what each template can read. It is for whoever writes or adapts your theme.

Which template, with what data

AddressTemplate, first match winsData
/home, else indexstart_here, shelves, latest, post_count
/writingindexposts, pagination
/aboutabout, page, postpost
/<topic>tag-<slug>, tag, indextag, posts, pagination
/<topic>/<slug>post-<slug>, postpost
/author/<slug>author-<slug>, author, indexauthor, posts, pagination
/search?q=search, then a page in pagequery, posts, pagination
/subscribesubscribe, then a page in pagepost
/offersoffers, then a list in pageoffers, post
/offers/<sku>offer-<sku>, offer, then Kōlea's own pageoffer, post
anything elseerror-404, error-4xx, errorstatusCode, message

The feed, sitemap, robots.txt, and /assets/* are made by Kōlea, not the theme. There is no routes file.

The front page

  • start_here: featured posts, newest first, up to 12.
  • shelves: topics set to show on the home page, busiest first, up to 8, each with its 3 newest posts.
  • latest: the 6 newest posts.
  • post_count: how many posts are published.

Each is empty on a new site, so wrap every section in #if.

Shapes

  • post: id, title, slug, html, excerpt, url, feature_image, feature_image_caption, featured, visibility, access, published_at, updated_at, reading_time, tags, primary_tag, authors, primary_author, hue, hue_cool, share_x_url.
  • tag (a topic): id, name, slug, description, url, count.posts, hue, hue_cool.
  • author: name, slug, url, profile_image, bio, count.posts. There is one author per site.
  • offer: sku, title, description, excerpt, url, price (formatted), amount (minor units), currency, for_sale, notice, buyers, letters (each headline, body, name, rating, verified), checkout_action, copy (a published launch's sections by key), sections (each key, label, html).
  • pagination: page, limit, pages, total, prev, next.

Globals

  • @site: title, description, url, logo, navigation, topics, signup_action, search_url, writing_url, about_url, social, now, and Ghost's flags.
  • @author: name, photo, short_bio, short_bio_html, url, social.
  • @profile: lede, what_i_do, links.
  • @custom: your theme's settings from package.json.
  • @config: posts_per_page.

Things to know

  • Put the kolea_head helper in every page's head. It writes the title, canonical, Open Graph, and feed tags.
  • Subscribe forms post to @site.signup_action with a field named email.
  • offer_buy draws an offer's Buy form and price prints its price; never write the Buy form by hand.
  • hue and hue_cool are numbers for OKLCH; set them as --h and derive colours in CSS.
  • Ghost features Kōlea lacks, such as comments and paid tiers, render nothing rather than breaking the page.
  • A get block may run 10 times per page and returns at most 100 items.