Description: Designing and customization of generated HTML using templates and template variables.

Setting up page layout is controlled by [Mako](https://www.makotemplates.org/) templates. Mako is well documented elsewhere, the following deals with Pagegen specifics.

Pages may specify a template by setting `Template` header.


## Themes

All templates are located in `themes/<theme name>/templates` directory. Set site theme in `site.conf` using `theme=<theme name>`.

Theme directory structure:

	my_theme/
	├── assets/
	└── templates/

On generation the `assets` directory and its sub directories are copied verbatim to `site/<environment>/assets/theme`. This is where all theme assets (javascript, css, images etc) for the theme are located.

The `templates` directory contains the theme mako templates, it must contain `pages.mako`, and may contain whatever other templates are required to render the site. In addition it may contain default templates, see below.


## Default templates

Templates may be created to as needed, but there must be at least one called `pages.mako`. The following templates will be used in specific circumstances, if they exist in the `themes/<theme name>/templates` directory.

| Name             | Purpose                                        |
| ---------------- | ---------------------------------------------- |
| author.mako      | Author profile template                        |
| authors.mako     | Listing of authors                             |
| directories.mako | Used if no `index` file defined in directory |
| pages.mako       | Mandatory, default template                    |
| tag.mako         | Listing the pages for a given tag              |
| tags.mako        | Listing the tags defined in page headers       |


## Template variables

The following context/variables are available to the templates.

| Name              | Description                 |
| ----------------- | --------------------------- |
| page              | <a href="<sc>page_url('/user-manual/site-and-page-attributes')</sc>">Page object</a>      |
| site              | <a href="<sc>page_url('/user-manual/site-and-page-attributes')</sc>">Site object</a>      |
| year              | yyyy                        |
| month             | mm                          |
| day               | dd                          |