Clarify themes in documentation with better examples

[henrifrancois]

Documentation issue

The documentation around themes has been confusing and from the point of understanding what Zola defines as theme as (which might be slightly different from the common understanding of a theme) to instructions on extending them.

Summary

Reflect the fact that a theme is not just a set of cosmetic enhancements (which from reading issues, people generally assume) but rather a predefined structure which can come into conflict with user defined pages. For instance, it is not clear how to get from the overview of Zola to the same project, but with a theme applied.

Proposed solution

• An addendum to the overview with a page detailing how to use a theme after having defined the content and displaying it.
• A definition of a theme in the appropriate section of the documentation
• Examples of modifying themes to fit specialized needs.

I am willing to work on this.

[Keats]

I would love a PR for it!

[doamatto]

I'll try to help out where I can as well (@henrifrancois feel free to touch bases with me or share a repo to keep it all in one PR). I think the only thing that keeps me from recommending Zola to others is that the documentation isn't as good as it could be.

[henrifrancois]

Sweet. I am going to try a draft PR with some of the proposed changes this weekend.

[henrifrancois]

Hi any chance I could get some feedback on linked draft PR? Otherwise I can just keep going and provide a more substantial PR soon.
My main worries were about breaking the documentation chances into several PRs that could be easier to review than one huge one, and have some guidance the best ways to make that happen?

[Keats]

I'll have a look but I prefer one big PR to review at once.

[henrifrancois]

Got it, I'll just do that then. I can get started asap.

[Keats]

Cool, I'll review it when you think it's done then!

[emdete]

How about this one? I ran into theme problems today and would need some help. As a newbie i did the beginners tour which ends in an incredible simple webpage so i installed a random theme from the suggestions list. but the theme wasnt even considered by zola. i reread all the doc, its downloaded, enabled in conf, ... no clue whats wrong. i didnt find a verbose mode for zola serv to get more information. i am lost here.

so some docs about themes would be incredible fine. :)

My problems were not at all about theming, it was more a misunderstanding on how zola works. So i started an alternative first-view-on-zola document in https://github.com/emdete/zolaschool - if that perspective is somehow helpful just use, comment, clone it :)

[BrendanBall]

As someone that loves open source, I'm glad this project exists.
However as someone trying to quickly setup a new simple site, and having to choose between 30 SSGs as recommended by cloudflare on https://developers.cloudflare.com/pages/framework-guides/, I'm not really sure why zola is being recommended as one of the best based on some searches.
I went through getting started on https://www.getzola.org/documentation/getting-started/overview/.
That was fine, however the page was bare, so I wanted to use a theme. I go to https://www.getzola.org/documentation/themes/installing-and-using-themes/ and follow the instructions:

1. download a theme
2. configure the theme in config.toml and additional theme specific settings under [extra].
3. run zola serve

but no profit, site is still as bare as previously.
The improved docs at #1541 have clarified it, so I'm not sure why it hasn't been merged for 2 years.
If I didn't have a weak spot for rust based projects, I would've moved onto another 1 of the 30 SSGs already.
I would really recommend to improve the getting started if you actually want people to end up choosing zola, especially since there's already a PR that has done the work.

[Keats]

The improved docs at #1541 have clarified it, so I'm not sure why it hasn't been merged for 2 years.

It's a draft and I forgot about it after a while. I've just merged it.

The docs will be rewritten eventually, they haven't really changed since the beginning. I don't use themes personally so this is an area where someone else would be better positioned to write.