On this page, you will be guided through the process of creating a new theme.
Pre-requisites
Chameleon uses Liquid as its templating engine. This means that all variables, like the title of an entry, some URL, or some setting you want to display, will be written in Liquid's syntax. Therefore, you better check out the how-to on the Liquid website, which provides a basic introduction into the Liquid syntax.
To follow this introduction, you will have to know HTML, and some CSS knowledge is also recommended. It's best to also know your way around in Chameleon, so you for example know which sort of pages Chameleon supports. First-time Chameleon users might be overwhelmed by the difficulty in learning to work with a new blogging engine and a new templating engine at the same time.
Getting started
When creating a new theme, the best you can do is copy one of the default themes and overwrite it step by step. All themes reside in the themes directory in the Chameleon root, copy one of the directories there and rename it (default for example). As first step, you may want to change the credentials in the theme.yml file in that directory. From there on, you'll change all theme files one by one.
The structure of a theme
A theme consists of the following files and directories:
- images contains all images used by the theme.
- javascripts contains all JavaScript files used by the theme.
- stylesheets contains all stylesheets used by the theme.
- templates contains all Liquid templates used by the theme.
- blog contains the templates for all pages on your blog.
- *.liquid are the Liquid templates.
- _*.liquid are "partials", templates included in other templates. That way, you can re-use code over several templates.
- layouts contains the lay-out for your blog.
- blog.liquid is the lay-out for your blog, in which one of the templates in templates/blog will be inserted.
- types contains the templates for each type (in future, the workings of this directory will likely be changed, so these templates can be provided with the types, and that they don't have to be included by the theme authors).
- blog contains the templates for all pages on your blog.
- theme.yml is a file with some information about the theme.
Adjusting theme.yml
The file theme.yml contains some basic information on the theme, which will be displayed on the "Manage Themes" page in the Admin Center. You can set the following details in the file:
- name (required): The name of your theme.
- version (required): The version of you theme. This can be written in any format you prefer.
- website: A link to the homepage of a theme, if it has one.
- description (required): The description of the theme, which will be displayed in the Admin Center. You can include some basic HTML here (for links, for example).
- author (required): A subsection with information about the theme author.
- name (required): The name of the author(s).
- e-mail: The e-mail address of the author(s). This is not displayed in the Admin Center, but can be useful if someone wants to contact you with a question about the theme.
- website: The author's website.
- license: The license under which you distribute your theme. This is not displayed in the Admin Center, but can be useful when someone wants to re-distribute your theme.
Creating the layout
The first thing we'll do to create our theme is to modify the "frame", the skeleton, in which every page will be encapsulated. The file templates/layouts/blog.liquid contains this skeleton. In it, you can define the HTML DOCTYPE, create the <head> section with all tags you would need, and open the <body> tag. In the body, you can create a header and a footer, and in between them, where the content of the page will be included, you should write {{ content_for_layout }}. This tag will be replaced with the contents of one of the templates.
An example lay-out might be:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>{{ option.general_blogname }}</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rel="stylesheet" href="{{ 'application.css' | url_for_stylesheet }}" type="text/css" />
{% if entry %}
<link rel="stylesheet" href="{{ entry.url_for_type_stylesheet }}" type="text/css" />
{% endif %}
</head>
<body>
<h1>{{ option.general_blogname }}</h1>
{{ content_for_layout }}
<p id="footer">Copyright by Me - Powered by <a href="http://chameleon.wikidot.com">Chameleon</a></p>
</body>
</html>
Editing the templates
In the templates, you can write regular HTML, combined with Liquid tags, blocks, filters and drops. These will then get parsed, and the parsed template will get included in the layout. That compiled file is sent to the user.
There are a lot of different Liquid tags, blocks, filters and drops in Chameleon, some available on all pages, some only on specific pages. This wiki has a complete list of all tags, blocks, filters and drops available in the templates, both those defined by Chameleon as these defined by Liquid.
The following templates should be available in each theme:
- show.liquid: The entry page.
- home.liquid: The home page.
- archive.liquid: A monthly archive.
- tag.liquid: A tag archive.
- search.liquid: A search.
- notfound.liquid: Rendered when the page the user requested was not found.
Note that you can include templates easily, so you can for example make a file _entries.liquid to display the list of entries on both the monthly archives, the tag archives, the search page and the home page.
Type-specific templates
This section is not written yet.
Using stylesheets, JavaScripts and images
This section is not written yet.
Help
You can ask any question concerning theming in Chameleon on the Chameleon help forum. If you would have any questions specifically related to Liquid, you can also ask them on the Liquid discussion board, of course, but on the Chameleon forums you will probably get better guidance on using Liquid in Chameleon.
