Ivy borrows its idea of themes from WordPress where a theme is a directory of templates, styles, and scripts that together provide the look and feel for a site.

A site's theme is completely independent of its content.

This idea is central. You can swap between themes and completely change the appearance of your site without touching its content.

Location

Themes should be placed in the site's lib directory, and the name of the active theme directory specified in the site's configuration file.

theme = "graphite"

Ivy ships with a small collection of bundled themes including graphite, the default theme you're looking at right now, and debug, a diagnostic theme useful when designing themes or debugging sites.

Note that you can override the currently active theme with the build command's --theme flag:

$ ivy build --theme debug

Ivy searches for a named theme first in the site's theme library, then (if it exists) in the global theme library specified by the $IVY_THEMES environment variable. Finally it searches among the default themes bundled with Ivy itself.

Structure

A theme is simply a directory; the theme's name is the name of the directory.

When building a website, Ivy looks for three subdirectories within the theme directory: resources, templates, and extensions.

resources

The content of the resources directory is copied to the output directory when the site is built. A theme should store its static assets in this directory, e.g. CSS, JavaScript, font, and image files.

templates

The templates directory is where Ivy looks for the theme's template files. This directory is also where Jinja and Ibis will look for files included in templates using {% include %} tags.

extensions

Themes can bundle extensions for Ivy by placing Python modules or packages in the extensions directory. These will be loaded automatically by Ivy.

A theme directory can contain other files and directories — e.g. a license file, readme file, etc. — which Ivy will simply ignore.

Template Files

Template files provide the HTML scaffolding for constructing pages — you can think of a template file as the mould into which your content will be poured.

There are countless templating languages and Ivy can use any of them, but it has builtin support for Jinja and Ibis. Ivy determines the language of a template file by looking at its extension — .jinja for Jinja and .ibis for Ibis.

You can add support for alternative templating languages via plugins.

Template Hierarchy

When Ivy generates a HTML page for a node it searches for the appropriate template file to use in reverse order of specificity (most specific first, least specific last).

For example, the node file:

src/foo/bar/baz.md

corresponds to the node:

<Node @root/foo/bar/baz//>

Ivy will search for a template file for this node in the following order:

1. node-foo-bar-baz.*
2. node-foo-bar.*
3. node-foo.*
4. node.*

Ultimately, Ivy will always check for a template file called node.* — this is the default template name and the only template file actually required by a theme.

A node can override this process by specifying a custom template name in its header:

---
template: my-custom-template
---

Note that the file extension should be omitted from the template name.