Themes

Layers

Theme files are looked up in three layers, first match wins:

1. theme/ in the content repo: site-specific overrides.
2. themes/<name>/: the theme selected by theme.name in site.yaml.
3. The built-in default theme, embedded in the binary.

So a theme only contains what it changes, and any site can tweak any theme by dropping a single file into theme/. Admins pick a theme on the Settings page. Like every settings save, the switch is test-built first, so a missing or broken theme is rejected before it’s committed.

Anatomy

themes/trunk/
  theme.yaml           name, version, description, author, homepage, license
  screenshot.png       optional, shown in the theme picker
  templates/
    base.html          the page shell; defines where "main" goes
    list.html          home page, pagination, and tag pages
    post.html  page.html  author.html  tags.html  404.html
    partials/*.html    shared templates, available everywhere
  static/              served at hashed, immutable URLs under /theme/

Reference static files with the asset function, which returns the hashed URL:

<link rel="stylesheet" href="{{asset "style.css"}}">

Other functions available to templates are absURL, date, tagURL and year. Every template gets .Site, .Theme, .Title, .URL, and whichever of .Post, .Page, .Author, .Posts, .Tags and .Pagination apply to the page.

How this site’s theme works

This site uses a theme called trunk, and it lives in the same repo as these words. A few tricks it uses:

• The home page is list.html. It checks {{if eq .URL "/"}} and renders the landing page instead of a plain post list.
• The docs layout is front matter. Pages with layout: docs get the sidebar. Unknown front matter keys are available as .Page.Meta.Extra.
• The sidebar is in site.yaml. A custom docs: list, read as .Site.Config.Extra.docs, keeps the order explicit.
• Fonts are self-hosted from static/fonts/, wired up with @font-face rules that use asset in base.html.

Code blocks are highlighted with Chroma CSS classes (.chroma .kn and friends), and your theme’s stylesheet decides the colors. Themes have no options for now: a different look is a different theme, which is cheap because a theme only contains the files it changes.