I am missing something to start using the product

Support
1

I am looking to use zola. However, I seem to have a problem to grasp part of the concept.

I don’t understand the relationship between the “themes” and “templates”. I was under the impression that even if I supply no “~/rv/templates/” file, the “~/rv/themes/zola-clean-blog…” will supply the necessary templates.

It did not work and “zola serve” displayed the “Welcome to zola!” page inviting me to create an index.html or install a themes. (their is an index.md and about.md in the “~/rv/content” directory.)

When I put an index.html to “augment” the themes “index.html”, zola serve return an error message: Error: Template ‘index.html’ is inheriting from ‘themes/zola-clean-blog/templates/index.html’, which doesn’t exist or isn’t loaded.

The files does exist at "~/rv/themes/zola-clean-blog/templates/index.html

I try a few others themes and in every cases, it is like it completely ignore the “~/rv/themes” directory. (ex: font not loaded, *.css no loaded, etc…)

Here what I did (Sorry if a little long): (On Ubuntu 18.04)

a) I downloaded (with git) and “cargo build --release” zola. Everything look good and no error.

b) I did a zola init rv

c) I downloaded a theme: zola-clean-blog Using “git clone GitHub - dave-tucker/zola-clean-blog: A port of the StartBootsrap Clean Blog theme for Zola” when within ~/rv/themes

d) create a new file in ~/rv/templates/index.html
just copying the information from the web.

{%/* extends “themes/zola-clean-blog/templates/index.html” /%}
{%/ block copyright /%}
Copyright %copy; Example, Inc. 2016-2019
{%/ endblock copyright */%}

e) I created a file about.md in ~/rv/content
+++
+++
followed by some text.

f) ~/config.toml include the following:
[extra]
# Put all your custom variables here

     theme = "zola-clean-blog"
     
     taxonomies = [
         {name = "categories", rss = true, paginate_by=5},
         {name = "tags", rss = true, paginate_by=5},

g) Then, when I execute zola, this follow:

jylandry@JYL:~/rv$ ~/zola/target/release/zola serve --interface 0.0.0.0
Building site...
**Error: Template 'index.html' is inheriting from 'themes/zola-clean-blog/templates/index.html', which doesn't exist or isn't loaded.**

here the directory structure (without the .git):

4 rv/static
5740 rv/themes/zola-clean-blog/static/img
2720 rv/themes/zola-clean-blog/static/webfonts
216 rv/themes/zola-clean-blog/static/js
216 rv/themes/zola-clean-blog/static/css
8896 rv/themes/zola-clean-blog/static
44 rv/themes/zola-clean-blog/sass
16 rv/themes/zola-clean-blog/content/pages
184 rv/themes/zola-clean-blog/content
12 rv/themes/zola-clean-blog/templates/tags
12 rv/themes/zola-clean-blog/templates/categories
52 rv/themes/zola-clean-blog/templates
20148 rv/themes/zola-clean-blog
20152 rv/themes
4 rv/sass
8 rv/content
8 rv/templates
20184 rv

I make a test copying all the files from one of the themes toward “~/rv/templates, ~/rv/sass …” and it seems to work after I use “zola build --base-url http://x.com”

This is what we should do: Copy the file from the themes toward our own content and templates?

2

What content is there in your index.html? Do you have a repo with it?

3

This is brand new – only minimal test content site.

The ~/rv/templates/index.html have only this content (and this is the only file in templates):

The ~rv/content site have 2 files: index.md and about.md – same content:

+++
+++

Jean-Yves Landry, 2020, COVID et la petite caravane dans le champ.

---- I try to use the ubuntu snap install (that zola 0.10.0 instead of 0.11.0) and I get the same result.
jylandry@seattle:~/rv$ zola serve
Building site…
Error: Template ‘index.html’ is inheriting from ‘themes/zola-clean-blog/templates/index.html’, which doesn’t exist or isn’t loaded.
j

You use the word “repo” but I am not sure what repository your are refering too.
This is a brand new site done with zola init and downloading the theme. Modify config.toml and put these 3 files in and that it.

4

I’m also kinda lost on how to use Zola with a theme.
From what I understand from the doc, if I want to start a project with the template from after-dark for example, I should be able to do it like that:

zola init
git clone https://github.com/getzola/after-dark.git themes/after-dark
cat >> content/_index.md<< EOF
+++
paginate_by = 5
+++
EOF
cat >> config.toml<< EOF
theme = "after-dark"
taxonomies = [
    {name = "categories", rss = true},
    {name = "tags", rss = true},
]
EOF

First note, if I never used a template engine that uses .md, I wouldn’t know that I have to add the +++ around paginate_by.

What I would expect is to get the same content than the demo here: https://zola-after-dark.netlify.app/

Since it’s not the case, there is definitely some bits missing in the documentation, because reading the documentation doesn’t tell me how I get anything similar to the demo.

After playing around, I saw that we need to add the theme and taxonomies before [extra]. That’s not clear from the documentation of the theme, and that’s a first trap if you don’t remember where this should be put from the Zola doc.
Let’s try again:

zola init
git clone https://github.com/getzola/after-dark.git themes/after-dark
cat >> content/_index.md<< EOF
+++
paginate_by = 5
+++
EOF
match='[extra]'
replace='
theme = "after-dark"
taxonomies = [
    {name = "categories", rss = true},
    {name = "tags", rss = true},
]

[extra]
'
while read -r line
do
  echo "${line//$match/$replace}"
done < "config.toml" > "config.toml.new" && mv "config.toml.new" "config.toml"

Basically, same thing script than before but we have to put the theme and taxonomies before the [extra], which is only for defining constants accross the templates it seems. For a first time user, this point was definitely not very clear, since, for me, I was adding “custom variables” as the comment says, as they weren’t defined in the generated config.toml.
Here we start having the theme loading at least.

For the rest, I think adding some more instructions on how to start adding posts or customizing the header and such in the theme documentation would be nice to have.

5

That’s unfortunately TOML being not super good :confused: There is no way to break out of a dict ([extra]) to go back to the top level.

Did you have a look at Installing & using themes | Zola?

You can’t clone the repository directly, you need to run zola init first and then clone the theme in the themes folder.

6

That’s unfortunately TOML being not super good :confused: There is no way to break out of a dict ( [extra] ) to go back to the top level.

For me the main problem is that the instruction saying to add theme and taxonomies are not clear enough. I may propose a pull request for that in the next few days, if I don’t forget.

Did you have a look at Installing & using themes | Zola?

Yes, and because of that I would have expected the demo pages to display by default.

You can’t clone the repository directly, you need to run zola init first and then clone the theme in the themes folder.

That’s what I did in both my scripts :slight_smile:

I will take some time to customize my theme and rebuild my website/blog using Zola, and I’ll try to propose a better documentation via github, hoping it will help other people.

1 Like
7

I have a problem that don’t seems obvious at first.

Because I was not able to use the themes properly, I just copied all the files in my own template/static/sass. It is almost working.

Independently of the fact that “config.toml” define: base_url = “http://qwa.jyl.farm”, their is still plenty of think that use http://127.0.0.1/ as the base URL.

Now, I start zola with: ~/zola/target/release/zola serve --base-url “qwa.jyl.farm” --interface 0.0.0.0
This seems to work OK. Except that the --base-url cannot specify http://. If it does, the resulting url become http://http//qwa.jyl.farm.

8

I just started using Zola (Thanks!) and also encountered similar issue:

I’ve followed the instructions to install a theme (cloning into themes/) and got an Error:

Error: Template 'page.html' is inheriting from 'index.html', which doesn't exist or isn't loaded.

when I’ve restarted the zola serve process and ran it again the main page showed up.

9

Which version of Zola?

10

0.12.2

11

Hm maybe zola serve doesn’t support adding a theme while it’s running? I thought it would work

12

I’d like to add a corollary, here.

It may not be obvious that items in the config.toml MUST be added in the same order as they appear in the documentation. It makes sense once you realize how TOML works, so it’s not technically a bug but probably this can be better explicitedly in the tutorial (which should not assume too much from the reader).

I see a couple of threads in the forum from people tripping over this detail. In my case was not loaded because by mistake the theme="" directive was after the [markdown] section.

WRONG

[markdown]
highlight_code = true
....
theme="after-dark"

RIGHT

theme="after-dark"
[markdown]
highlight_code = true
....
13

@jylandry this should be {% extends "zola-clean-blog/templates/index.html" %}, as explained in the docs. I agree this is confusing to say the least, and previously argued for a static string pointing to the current string when resolving template paths. I don't think it's common enough was the reason for not implementing it at the time, so feel free to express your concerns.

@maximborges I agree theme documentation should help with that. Feel free to checkout my water.css-based theme which should have good documentation. It’s not ready for prime time just yet but it’s already used by a bunch of websites and should be fairly extensible.

Yes that’s because zola serve changes the baseURL so your browser can access it. When built for production with zola build, the settings in the config file will be respected. As you noted, zola serve can take a -u flag which forces a certain base domain but which does not take a scheme (HTTP/HTTPS) because zola doesn’t serve with TLS (for good reasons).

Yes that’s not necessarily obvious for someone who is not familiar with TOML. Would you like to help improve the documentation?