zola/docs/content/documentation/themes/installing-and-using-themes.md

66 lines
2.2 KiB
Markdown
Raw Normal View History

2017-10-01 03:51:43 +00:00
+++
title = "Installing & using themes"
weight = 20
+++
## Installing a theme
The easiest way to install a theme is to clone its repository in the `themes`
2017-10-01 03:51:43 +00:00
directory.
```bash
$ cd themes
$ git clone THEME_REPO_URL
```
Cloning the repository using Git or another VCS will allow you to easily
update. Alternatively, you can download the files manually and place
2017-10-01 03:51:43 +00:00
them in a folder.
You can find a list of themes [here](@/themes/_index.md).
2017-10-01 03:51:43 +00:00
## Using a theme
Now that you have the theme in your `themes` directory, you need to tell
Zola to use it by setting the `theme` variable in the
[configuration file](@/documentation/getting-started/configuration.md). The theme
name has to be the name of the directory you cloned the theme in.
2017-10-20 10:35:23 +00:00
For example, if you cloned a theme in `themes/simple-blog`, the theme name to use
2017-10-01 03:51:43 +00:00
in the configuration file is `simple-blog`.
## Customizing a theme
Any file from the theme can be overriden by creating a file with the same path and name in your `templates` or `static`
directory. Here are a few examples of that, assuming that the theme name is `simple-blog`:
2017-10-01 03:51:43 +00:00
```plain
templates/pages/post.html -> replace themes/simple-blog/templates/pages/post.html
templates/macros.html -> replace themes/simple-blog/templates/macros.html
2017-11-17 21:40:41 +00:00
static/js/site.js -> replace themes/simple-blog/static/js/site.js
2017-10-01 03:51:43 +00:00
```
You can also choose to only override parts of a page if a theme defines some blocks by extending it. If we wanted
to only change a single block from the `post.html` page in the example above, we could do the following:
```
{% extends "simple-blog/templates/pages/post.html" %}
{% block some_block %}
Some custom data
{% endblock %}
```
Most themes will also provide some variables that are meant to be overriden. This happens in the `extra` section
of the [configuration file](@/documentation/getting-started/configuration.md).
Let's say a theme uses a `show_twitter` variable and sets it to `false` by default. If you want to set it to `true`,
2017-10-01 03:51:43 +00:00
you can update your `config.toml` like so:
```toml
[extra]
show_twitter = true
2017-10-01 03:51:43 +00:00
```
You can modify files directly in the `themes` directory but this will make updating the theme harder and live reload
won't work with these files.