From debf60e3b33e824119a11778acbd33e7ab3a6528 Mon Sep 17 00:00:00 2001 From: "Henri E. Francois" <7969061+henrifrancois@users.noreply.github.com> Date: Fri, 19 May 2023 06:44:40 -0400 Subject: [PATCH] Clarifying documentation around themes. (#1541) - Defined a theme in Zola - Clarified configuration of themes - Clarified theme template functionality --- docs/content/documentation/themes/extending-a-theme.md | 4 ++-- .../documentation/themes/installing-and-using-themes.md | 1 + docs/content/documentation/themes/overview.md | 4 +++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/content/documentation/themes/extending-a-theme.md b/docs/content/documentation/themes/extending-a-theme.md index d403427cd3..3910c56822 100644 --- a/docs/content/documentation/themes/extending-a-theme.md +++ b/docs/content/documentation/themes/extending-a-theme.md @@ -1,5 +1,5 @@ +++ -title = "Extending a theme" +title = "Customizing a theme" weight = 30 +++ @@ -7,7 +7,7 @@ When your site uses a theme, you can replace parts of it in your site's template ## 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 diff --git a/docs/content/documentation/themes/installing-and-using-themes.md b/docs/content/documentation/themes/installing-and-using-themes.md index 16b5bc4a11..e704b703af 100644 --- a/docs/content/documentation/themes/installing-and-using-themes.md +++ b/docs/content/documentation/themes/installing-and-using-themes.md @@ -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 diff --git a/docs/content/documentation/themes/overview.md b/docs/content/documentation/themes/overview.md index 000668446a..6c9c5e827f 100644 --- a/docs/content/documentation/themes/overview.md +++ b/docs/content/documentation/themes/overview.md @@ -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.