# water theme for Zola A multi-lingual, lightweight and responsive theme built on water.css. It's intended to powerful yet simple, so if the theme gets in your way, or if something isn't clear, please consider it an issue and report it [on tildegit](https://tildegit.org/southerntofu/zola-water) or by email to the maintainer (MyUserName@thunix.net). # Setup Just download this repository and place it in your site's `themes/water` directory. Then, in your config.toml: ``` theme = "water" ``` If you would like to receive updates directly via git, you can clone the repository like this: ``` $ cd path/to/site/ $ mkdir themes # If it doesn't exist yet $ git clone https://tildegit.org/southerntofu/zola-water themes/water ``` Then you can fetch updates, from the `zola-water` repository, with the `git pull` command. Please don't modify templates directly in the theme folder, as this would cause problems during updates. Instead, refer to the [Configuration](#configuration) and [Customization](#customization) sections. ## Updates **This theme is a work-in-progress**. It's good enough for me and some other folks to use and cutomize for our needs, however some things will evolve over time to improve the overall experience. **Breaking changes** will be introduced, though never without reason. The overall design of this theme takes careful evaluation, to avoid having to revert changes in the future. # Configuration If you want to simply configure the theme to match your needs, there's a few options at your disposal. If you want to replace parts of the templates, please head over to the [Customization](#customization) section of this page. ## Base template There's a few options to configure the source for different parts of the base template. At the moment, only `header` and `menu` are configurable: - `header` defines the source for the top of the page - `menu` defines the source for the navigation menu, right under the `header` page Each of these settings can be either the path to a page from the content folder, or "disabled". Setting a page requires a full path, including the `.md` extension, because Zola loads pages from either `page.md` or `page/index.md`. Disabling these parts with the "disabled" keyword. **Note**: Pages defined in the config, like `header = _common/header.md` will be resolved according to the current language, so the french version of the site will call `_common/header.fr.md` automatically. This will provoke a crash when such a page is not translated in not all defined languages. (**TODO**: open a ticket on zola for support of `required` param in `get_page` function). If you need more flexible customization of the templates, please refer to the [Customization](#customization) section on how to extend the theme's template from your site's templates folder. **TODO**: In the future, every macro will have a corresponding shortcode, so that basic configuration of the layout can be achieved exclusively via Markdown files. ## Styles ### color `color = "dark"` determines the default color scheme displayed to your users. This can be either `light` or `dark`, and is only applied to browsers who do not implement the [prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) media query. More modern browsers will display the website as they please, and out of respect for your users, no simple way to change this is provided. ### stylesheets `stylesheets = [ "style.css" ]` determines a list of additional stylesheets to load in the main template. By default, the theme provides a style.css stylesheet (generated from [this SASS file](https://tildegit.org/southerntofu/zola-water/src/branch/master/sass/style.scss)). You can remove this stylesheet from the `stylesheets` variable and/or add stylesheets of yours: - `stylesheets = []` disables any additional stylesheet - `stylesheets = [ "style.css", "custom.css" ]` adds custom.css to the theme's stylesheets - `stylesheets = [ "custom.css" ]` disable the theme's style.css and use custom.css instead ### max_width_for `max_width_for = "main"` determines what part of the site has the it's CSS `max-width` property set. Upstream water.css applies it to the whole page, while some Zola sites may want to have a fullwidth header, for instance. This setting can be "main" (default) or "body". To have the authentic water.css experience, set it to "body". The default value "main" applies it only to the main part of the page. ### max_width `max_width = "800px"` determines the max-width applied to the `max_width_for` element. The default is 800px, as defined in water.css. ## Homepage By default, the homepage (`content/_index.md`) is built as a landing page, taking the file's Markdown content into the main area of the website. However, the homepage can also be used to display a section's latest articles with the `home_section` setting. Here's an overview of the settings specific to the homepage. ### home_title `home_title = true` can be true or false, configuring whether the section's title is displayed on the homepage. This applies to the homepage's title when `home_section` is not used(default), and to the home section's title otherwise. ### home_section `home_section = ""` defaults to treating the home page as a simple page without children. Setting this variable to a section's name displays the latest articles of this section as the homepage. Example: use `home_section = "blog"` to feature the blog/ section on the homepage ### home_fullarticles (when using home_section) `home_fullarticles = false` decides whether to show article contents on the homepage. When disabled, articles will have their summary displayed, or simply their title/date when they don't have a summary. This option only applies to sites using a `home_section`. ### section_fullarticles `section_fullarticles = false` decides whether to show articles contents in a section. When disabled, articles will have their summary displayed, or simply their title/date when they don't have a summary. This setting can be overriden for each section with the `extra.fullarticles` field. ## Page sources If your website sources are published somewhere, you can display a URL (currently only in the footer) to each page's source, by configuring a `[extra.forge]` block in the config file. This block should contain a single `browse` field containing the baseURL to which the page/section path will be added to form the entire link to the source. As trailing slashes are trimmed in the template itself, the URL may end with a `/`. For example: ``` [extra.forge] browse = "https://lab.example/foo/bar/src/branch/main" ``` ## Missing translations The `extra.missing_translations` setting configures what to do when a translation string is missing. It can have the following values: - `error` (default) will fail the build with an error message, as is default zola behavior - `placeholder` will output the requested translation key (eg. `source`) instead of an actual translation - any other value is interpreted as a fallback language to query translations from when a specific string is missing # Customization ## Extending templates Theme templates can be extended from your site templates. This means you can replace any "block" defined in the theme templates. The template path needs to be prepended with `water/templates/`. If your site's section.html wants to override the content block of the theme's section, it can do like this: ``` {% extends 'water/templates/section.html' %} {% block content %}
The current language's menu is in file {{ widgets::i18n_path(path="menu.md") }}
``` #### i18n_content Takes a `path` parameter to a content page (not section). Return the page's content in the current language. Example: ``` ``` #### i18n_url Takes a `path` parameter which is a URL relative to your site. Returns the requested URL, with the current language inserted between the base_url and the path (eg. "rss.xml" => "BASEURL/fr/rss.xml"). Example: ``` ``` **Note**: this macro does not lookup translations, because these are not supported on all content (only pages and sections), but naively constructs the URL. Only use it for content you know share the same slug across languages. The base URL is also assumed to be the same across languages, because localized base URLs is not yet supported by zola. ### Translating taxonomies In order to support translating names for taxonomies, you simply need to define those with an additional `lang` key in config.taxonomies: ``` taxonomies = [ { name = "tags", lang = "en", rss = true }, { name = "tags", lang = "fr", rss = true }, { name = "authors", lang = "en", rss = true }, { name = "auteurices", lang = "fr", rss = true }, ] ``` Then, your translated pages can use the translated taxonomy names. Example page.fr.md: ``` [taxonomies] tags = [ "ssg", "tutoriel" ] auteurices = [ "foobar" ] ``` **Note**: I'm not sure if that's a feature or an anti-feature, for reasons explained here : https://zola.discourse.group/t/rfc-internationalization-system-rework/546/20 . **TODO**: Implement/Document translations for display name and description of taxonomies. # Template widgets The theme features some nice, user-friendly content-organizing patterns such as described in [this article](https://staticadventures.netlib.re/blog/multi-column-layout/). For the moment, only a menu widget is provided, but more are coming! ## menu widget This widget comes in handy when you need to build a list of link, that you can further style with CSS. It takes a `content` argument and divides it according to the thematic breaks, furthermore stripping paragraph tags added during Markdown processing. **Note**: this macro relies on ugly HTML hacks that do not work with every content, i hope in the future zola allows us to access the raw markdown content and maybe even exposes a filter to split a page by thematic breaks. Example: ``` {{ widgets::menu(path="_common/menu.md") }} ``` Sample menu (can be translated): ``` +++ +++ [Home](@/_index.md) === [About](@/about.md) === [Contact](@/contact.md) ``` # For the future ## Current limitations This theme is already quite cool, but there's a few limitations i would like to tackle: - if you configure a header/menu = "foo.md", it needs to be translated in every language otherwise the site will crash; if you have ideas how to fix this without a [has_page](https://zola.discourse.group/t/rfc-i18n/13/28) template function, let me know! - if you configure a header/menu, it cannot be the index page because of some weird reason i have no idea about - pagination cannot work on the index page, because index.html doesn't know about the home section's paginator (only the home's paginator) ; maybe we could count the home section's children and auto append a link to SECTION/page/2 when it's more than X? - we need more template blocks, for more customizability, so you don't have to edit huge chunks of templates just to modify a single value ## Future plans - ensure really good accessibility - test right-to-left languages - provide some interesting shortcodes - support other plug-and-play CSS stylesheets than water.css - support using only relative URLs so the same site output can be used across different baseURLs - add some cool, useful templates: - FAQ - "about me" - a contributing guide page produced by the theme - alternative names page to discover how to access the same page over different browsers/protocols - test results page, to integrate with a CI - build log page, to integrate with a CD