- **extra.image**: an optional image for the post.
If omitted, a default image is used instead.
The image is displayed on the blog's main page and on the posts detail page.
---
## Localization
Consider this text on a page where a blog post is published as an example: `Published on July 04, 2023; 1,234 words`.
If your blog is in the German language, you want to have `Veröffentlicht am 04. Juli 2023; 1.234 Wörter` instead.
Not only the text should be translated, but also the date and number formats are different.
And you want a text like `1 word` or `1 Wort`, because the singular form should be used where applicable.
This theme takes care of that.
To localize your blog with this theme:
1. Pick your desired language by setting the `default_language` in `config.toml`.
As of now, English (`en`) and German (`de`) have language resources available in the `i18n` directory.
If your language is not supported yet, just create a new resource file with your translations.
Use the file `en.toml` as a template for your own translations.
Use the correct language code for the file name, e.g. `eo.toml` for Esperanto.
Only languages that read from left-to-right (ltr) are supported by this theme.
2. The theme will automatically display all theme-specific string resources in the chosen language.
3. The content that you provide should match this language.
But that is your responsibility.
The theme will not translate your content.
If you need to define your own date format, look [here](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) for supported specifiers.
---
## Integrating in theme folder
This project is structured as a stand-alone Zola site.
This section is for those who might want to integrate the theme into an existing Zola website.
You can do so by moving the relevant theme files to the `themes/zolarwind` directory.
All other files stay in the root directory.
If you have your own files there, you need to merge them with the ones from this theme.
You also need to adjust the `config.toml` and `package.json` files in the root accordingly.
I will only show you the relevant directories that need to be moved.
This is the directory structure of the stand-alone site, where the theme is in the root directory:
```
/
├── css
├── i18n
├── static
│ ├── css
│ ├── img
│ └── js
├── templates
└── theme.toml
```
Create a new directory `themes/zolarwind` and move the following files and directories there:
```
/
├── static
│ └── css
└── themes
└── zolarwind
├── css
├── i18n
├── static
│ ├── img
│ └── js
├── templates
└── theme.toml
```
The `static/css` directory is a special case.
It contains the generated Tailwind CSS file with the name `generated.css`.
It will stay in its original location.
This file is generated from the file `css/main.css`, which is the input for the CSS generation.
The generation process can be triggered with a script in the `package.json` file.
**You only need to adjust and run the script** in `package.json` if you make changes to the theme's template files or use new Tailwind CSS classes directly in your content files.
Since the source file `css/main.css` has moved to the directory `themes/zolarwind/css/main.css`, we need to adjust the script in `package.json` accordingly.
This is how the relevant part of it looks like for the stand-alone site:
Since you now use Zolarwind as a theme, you need to declare it in the `config.toml` file.
The theme's files have moved to the directory `themes/zolarwind`, so you need to adjust the only reference to the theme's files in the `config.toml` file accordingly by changing the `path_language_resources` entry:
If you want to adjust the CSS of the theme to your needs, you will need to edit the files in the `templates` and `css` directories.
While you do this, you should make sure that the CSS file `static/css/generated.css` is up-to-date.
This file is generated from the file `css/main.css`, and all the files that are configured as a pattern in `tailwind.config.js`:
-`css/main.css`
-`themes/**/*.html`
-`templates/**/*.html`
-`content/**/*.md`
So whenever one of these files changes, you need to run the script `css:build` from the `package.json` file.
To accomplish this, you need to have `Node.js` and all dependencies from `package.json` installed (with `npm install`).
Then you can run the script with `npm run css:watch`.
It monitors all files mentioned above and triggers the CSS generation whenever a relevant file changes.
This ensures, that the file `static/css/generated.css` is always up-to-date.
I recommend to have two terminals open.
In one terminal, run `zola serve` to start the Zola server.
In the other terminal, run `npm run css:watch` to start the CSS generation whenever a relevant file changes.
That way, your local web browser will automatically reload the page with the updated CSS whenever you change a file.
---
## Remarks
### Typography for markdown
I'm not using `@tailwindcss/typography` for styling of markdown files.
I don't like how it looks.
Instead, I use `@apply` in the `css/main.css` file.
The `@apply` directive in Tailwind CSS enables you to compose utility classes into custom CSS classes.
This makes it possible to apply multiple utility styles within a single class, making it efficient to style markdown content.
This approach has pros and cons.
But it gives me fine-grained control over how the end result looks like.
While it is time-consuming, I prefer this solution over the `@tailwindcss/typography` plugin.
Yes, I'm reinventing the wheel here, because for common typographic patterns, I'm just recreating what's already provided by the typography plugin.
### Serve KaTex files locally
All KaTex files are included in the `static` directory for this theme.
Using KaTeX (or any other library) by serving it from a Content Delivery Network (CDN) has implications concerning the General Data Protection Regulation (GDPR) and the use of cookies:
- **Third-Party Requests & Data Privacy**: When you load resources from a CDN, it triggers third-party requests to the CDN's servers.
These servers might log your IP address, user agent, and other request-related metadata.
Under GDPR, IP addresses can be considered personal data.
By serving KaTeX from your domain, you reduce third-party data transfers, limiting the amount of personal data you expose to external entities.
- **Cookies**: Many CDNs set cookies for various reasons, including analytics or performance optimizations.
These cookies can track users across different websites that use the same CDN, potentially infringing on their privacy rights.
By hosting KaTeX on your domain, you have full control over the cookies set and can ensure compliance with GDPR.
- **Consent**: If you're using a CDN that sets cookies or collects data, you might need to get explicit user consent before loading resources from that CDN.
This can complicate user experience and lead to a reduced site performance for users who opt-out.
By self-hosting, you circumvent this issue.
- **Transparency & Control**: By self-hosting, you know exactly which version of KaTeX you're using and can ensure there are no modifications or unexpected behaviors.
With CDNs, there's a minor risk of the library being compromised, which could affect all sites using that resource.
- **Data Transfer Outside the EU**: If the CDN servers are located outside the European Union, you might be transferring data out of the EU,
which adds another layer of GDPR compliance requirements.
By self-hosting, you ensure that user data doesn't leave the region unless you specifically choose a hosting solution outside the EU.
---
## Contributing
Contributions are always welcome!
If you see areas of improvement or want to add features, please submit a PR.
I'm especially interested in more translations.
See folder `i18n` for what's available and what is not.
Just use the file `en.toml` as a template for your own translations.
