coleslaw/docs/themes.md

Themes

The theming support in coleslaw is very flexible and relatively easy to use. However it does require some knowledge of HTML, CSS, and how coleslaw processes content.

To understand how coleslaw works, a look at the hacking documentation will prove useful. This document focuses mainly on the template engine and how you can influence the resulting HTML.

High-Level Overview

Themes are written using Closure Templates. Those templates are then compiled into functions that Lisp calls with the blog data to get HTML. Since the Lisp code to use theme functions is already written, your theme must follow a few rules.

Every theme must be in a folder under "themes/" named after the theme. The theme's templates must start with a namespace declaration like so: {namespace coleslaw.theme.$MY-THEME-NAME}.

A theme must have three templates which take specific arguments (to be described later).

1. Base
2. Post
3. Index

Two types of pages

Coleslaw generates two types of pages: index pages and post pages. Every page other than those in the posts/ directory is an index.

Every page uses the base.tmpl and fills in the content using either the post or index templates. No important logic should be in any template, they are only used to provide a consistent layout.

• base.tmpl This template generates the outer shell of the HTML. It keeps a consistent look and feel for all pages in the blog. The actual content (i.e., not header/footer/css) comes from other templates.

• index.tmpl This template generates the content of the index pages. That is, any page with more than one content object, e.g. the homepage.

• post.tmpl This templates generates content for the individual posts.

Here's a visual example to make things clearer:

INDEX HTML FILES                    INDIVIDUAL POST HTML FILES
|-------------------------|         |-------------------------|
| base.tmpl               |         | base.tmpl               |
|                         |         |                         |
|  |-------------------|  |         | |------------------|    |
|  |  index.tmpl       |  |         | | post.tmpl        |    |
|  |                   |  |         | |                  |    |
|  |-------------------|  |         | |------------------|    |
|                         |         |                         |
|-------------------------|         |-------------------------|

Note on Style Sheets (css)

If you only want to change the way the blog is styled, it is probably simplest to either modify the existing default theme, hyde, or copy it in entirety and then tweak only the CSS of your new theme. A large amount of visual difference can be had with a minimum of (or no) template hacking. There is plenty of advice on CSS styling on the web. I'm no expert but feel free to send pull requests modifying a theme's CSS or improving this section, perhaps by recommending a CSS resource.

Creating a Theme from Scratch (with code)

Step 1. Create the directory.

A theme name must be a valid lisp symbol. For this example, we'll use trivial, so create a themes/trivial directory in the coleslaw repo.

Step 2. Create the templates.

As described above, we need 3 template files base.tmpl, post.tmpl and index.tmpl. Initially, let's just create the simplest theme that compiles correctly.

base.tmpl:

{namespace coleslaw.theme.trivial}
{template base}
{/template}

post.tmpl:

{namespace coleslaw.theme.trivial}
{template post}
{/template}

index.tmpl:

{namespace coleslaw.theme.trivial}
{template index}
{/template}

This will create three template functions that coleslaw can find, named base, post, and index.

Step 3. Use it in your config.

At this point, you can change the :theme in your .coleslawrc to trivial and then generate your blog with (coleslaw:main). However, all the HTML files will be empty because our templates are empty!

Intermezzo I, The Templating Language

The templating language is documented elsewhere. However as a short primer:

• Everything is output literally, except template commands.
• Template commands are enclosed in { and }.
• Variables, which are provided by coleslaw, can be referenced inside a template command. So to use a variable you have to say {$variable} or {$variable.key}. WARNING: At present, cl-closure-template does not have great debugging. If you typo this, e.g. ${variable}, you will receive an uninformative and apparently unrelated error. Also, attempted access of non-existent keys fails silently. We are exploring options for making debugging easier in a future release.
• If statements are written as {if ...} ... {else} ... {/if}. Typical examples are: {if $injections.body} ... {/if} or {if not isLast($link)} ... {/if}.
• Loops can be written as {foreach $var in $sequence} ... {/foreach}.

Intermezzo II, Variables provided by Coleslaw

The variable that should be available to all templates is:

• config This contains the .coleslawrc content.

Base Template Variables

• raw HTML generated by a sub template, index or post.
• content The object which was used to generate raw.
• pubdate A string containing the publication date.
• injections A list containing the injections. Injections are used by plugins mostly to add Javascript to the page.

Index Template Variables

• tags A list containing all the tags, each with keys name and url.
• months A list of all the content months, each with keys name and url.
• index This is the meat of the content. This variable has the following keys:
  • content, a list of content (see below)
  • name, a name to use in links or href tags
  • title, a title to use in H1 or header tags
• prev Nil or the previous index with keys: url and title.
• next Nil or the next index with keys: url and title.

Post Template Variable

• prev
• next
• post All these variables are post objects. prev and next are the adjacent posts when put in chronological order. Each post has the following keys:
  • url, the relative url of the post
  • tags, a list of tags (each with keys name and url)
  • date, the date of posting
  • text, the HTML of the post's body
  • title, the title of the post

Step 4. Include the content

NOTE: We can keep the template engine from escaping raw HTML by adding a |noAutoescape clause to commands, like so: {$raw |noAutoescape}.

Let's now rewrite base.tmpl like this:

{namespace coleslaw.theme.trivial}
{template base}
<html>
  <head><title>Trivial Theme For Coleslaw</title></head>
  <body>
    <h1>All my pages have this title</h1>
    {$raw |noAutoescape}
  </body>
</html>
{/template}

A simple index.tmpl looks like this:

{namespace coleslaw.theme.trivial}
{template index}
{foreach $obj in $index.content}
<h1>{$object.title}</h1>
  {$object.text |noAutoescape}
{/foreach}
{/template}

And a simple post.tmpl is similarly:

{namespace coleslaw.theme.trivial}
{template post}
<h1>{$post.title}</h1>
  {$post.text |noAutoescape}
{/template}

Conclusion

All of the files are now populated with content. There are still no links between the pages so navigation is cumbersome but adding links is simple. Just do: <a href="{$config.domain}/{$object.url}">{$object.name}</a>.