Skip to content

Commit

Permalink
Clarifying documentation around themes. (getzola#1541)
Browse files Browse the repository at this point in the history
- Defined a theme in Zola
 - Clarified configuration of themes
 - Clarified theme template functionality
  • Loading branch information
henrifrancois authored and selfisekai committed Nov 3, 2023
1 parent 6f903cd commit 87f9d8b
Show file tree
Hide file tree
Showing 3 changed files with 6 additions and 3 deletions.
4 changes: 2 additions & 2 deletions docs/content/documentation/themes/extending-a-theme.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
+++
title = "Extending a theme"
title = "Customizing a theme"
weight = 30
+++

When your site uses a theme, you can replace parts of it in your site's templates folder. For any given theme template, you can either override a single block in it, or replace the whole template. If a site template and a theme template collide, the site template will be given priority. Whether a theme template collides or not, theme templates remain accessible from any template within `theme_name/templates/`.

## Replacing a template

When a site template and a theme template have the same path, for example `templates/page.html` and `themes/theme_name/templates/page.html`, the site template is the one that will be used. This is how you can replace a whole template for a theme.
When your site uses a theme, the generated structure follows the theme's structure whenever possible, i.e. there are no user defined templates with the same name and relative path as the theme's; for example: with two files `templates/page.html` and `themes/theme_name/templates/page.html`, the site template is the one that will be used. Such a conflict results in the theme's template being ignored in favor of the template defined by the user.

## Overriding a block

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ name has to be the name of the directory you cloned the theme in.
For example, if you cloned a theme in `themes/simple-blog`, the theme name to use
in the configuration file is `simple-blog`. Also make sure to place the variable in the top level of the
`.toml` hierarchy and not after a dict like [extra] or [markdown].
Some themes require additional configuration before they can work properly. Be sure to follow the instructions found on your chosen theme's documentation to properly configure the theme.

## Customizing a theme

Expand Down
4 changes: 3 additions & 1 deletion docs/content/documentation/themes/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@ title = "Overview"
weight = 10
+++

Zola has built-in support for themes that makes it easy to customise and update them.
Themes are collections of layouts and styles used to facilitate the creation and management of Zola projects. As such, themes are Zola projects which provide their own templates, content and even static assets.

Zola has built-in support for themes which makes it easy to customise and update them.

All themes can use the full power of Zola, from shortcodes to Sass compilation.

Expand Down

0 comments on commit 87f9d8b

Please sign in to comment.