search

getzola / zola

A fast static site generator in a single binary with everything built-in. https://www.getzola.org
https://www.getzola.org
MIT License
13.12k stars 925 forks source link

Clarify themes in documentation with better examples #1532

Open henrifrancois opened 3 years ago

henrifrancois commented 3 years ago

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

I am willing to work on this.

Keats commented 3 years ago

I would love a PR for it!

doamatto commented 3 years ago

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 commented 3 years ago

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

henrifrancois commented 3 years ago

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 commented 3 years ago

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

henrifrancois commented 3 years ago

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

Keats commented 3 years ago

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

emdete commented 2 years ago

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 commented 1 year ago

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 https://github.com/getzola/zola/pull/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 commented 1 year ago

The improved docs at https://github.com/getzola/zola/pull/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.