Clarify which customization steps are mandatory before `zola serve` succeeds

[virtualritz]

Your justint.github.io repo's README states:

Don't just fork/copy: there are specific things in here developed just for this site alone [...]

However, adding the Papaya theme is rather frustrating compared to doing exactly the above: forking justint.github.io.

I start from a clean zola init and add the theme.

After doing everything before Customization in the README.

❯ zola serve
Building site...
Warning: config.toml contains both default language specific information at base and under section `[languages.en]`, which may cause merge conflicts. Please use only one to specify language specific information
Checking all internal links with anchors.
> Successfully checked 0 internal link(s) with anchors.
-> Creating 0 pages (0 orphan) and 2 sections
Error: Failed to serve the site
Error: Failed to render pager 1
Error: Reason: Failed to render 'blog.html'
Error: Reason: Variable `config.extra.color_mode` not found in context while rendering 'blog.html'

Ok, so I add color_mode to my config.toml. This is not mentioned anywhere in the README btw.

Try again:

❯ zola serve
Building site...
Warning: config.toml contains both default language specific information at base and under section `[languages.en]`, which may cause merge conflicts. Please use only one to specify language specific information
Checking all internal links with anchors.
> Successfully checked 0 internal link(s) with anchors.
-> Creating 0 pages (0 orphan) and 2 sections
Error: Failed to serve the site
Error: Failed to render section '/home/moritz/code/virtualritz.github.io/content/_index.md'
Error: Reason: Failed to render 'index.html' (error happened in a parent template)
Error: Reason: Variable `config.extra.menu_items` not found in context while rendering 'index.html'

Ok, so the menu is mandatory. I read the resp. Customization section, add it, and try again:

❯ zola serve
Building site...
Warning: config.toml contains both default language specific information at base and under section `[languages.en]`, which may cause merge conflicts. Please use only one to specify language specific information
Checking all internal links with anchors.
> Successfully checked 0 internal link(s) with anchors.
-> Creating 0 pages (0 orphan) and 2 sections
Error: Failed to serve the site
Error: Failed to render section '/home/moritz/code/virtualritz.github.io/content/_index.md'
Error: Reason: Failed to render 'index.html'
Error: Reason: Function call 'resize_image' failed
Error: Reason: `resize_image`: Cannot find file: /static/banner.jpg

That's when I gave up and forked justint.github.io and started modifying it. ☺

I guess I am trying to say: if you want users to not fork justint.github.io there are two options:

1. Improve onboarding documentation for the theme in the README. I.e.: what do people need to do exactly before zola serve succeeds after adding the Papaya theme?
2. Create a template repo. that can be forked. I.e. justint.github.io but stripped of specifics.

[Meeeee6623]

Real! Same problem here

[garyrob]

Same problem here!

[jamesmagoo]

I really like this theme - looks amazing - thank you @justint

I'm trying to get started and am getting the below error also. I just followed the steps.

Is there a fix for this?

[markstock]

The steps that I needed to add to make the theme useful are:

cp themes/papaya/templates/blog.html templates/
cp themes/papaya/templates/base.html templates/
cp -pr themes/papaya/templates/macros templates/
cp themes/papaya/templates/projects.html templates/
cp themes/papaya/static/banner.jpg static/

Also, add this to config.toml, under the [extras] section: color_mode = "auto"

Finally, when you add theme="papaya" to config.toml, it has to be above all the subsections (near or at the top of the file).

[jamesmagoo]

@markstock Thank you! that worked nicely 😃