Incorrect index file generated(?)

[gl326]

This is likely a skill issue, as it's my first time trying to use Zola, Github Actions, Github Pages, and static site generation in general. But I'll report my experience nonetheless since maybe it will help identify where the documentation here may be lacking.

I have have a repo with a Zola site all setup, and when I test it using zola serve it looks great. It's quite a default setup, with the site output going to the public folder etc. I haven't modified advanced settings anywhere to my knowledge.

I followed the instruction in the readme here to the best of my ability; created a Github action, pasted in the basic one provided in the readme. Enabled actions, enabled pages, corrected several build errors to do with incorrect image formats. I'm at the stage now where any commit causes the GitHub action to run and for a site to be deployed to GitHub pages, which is great.

However, rather than using my index template defined in template/index.html, the generated index.html is based on the ReadMe.md in my repo root directory. I verified this by downloading the generated artifact.tar file; it's not raw text, it's a properly generated html file using the contents of my readme.md file. Other assets are present in subfolders, including all my template html pages (including index.html!) and content files, but they don't seem to be using my style or theme at all.

Since I've never actually successfully deployed a website, I don't know what the output artifact.tar is supposed to look like. I would guess that it is using my root folder instead of the public subdirectory. The output artifact.tar looks a lot like my repo, but with the "public" folder conspicuously missing. The ReadMe here suggests that by default, with no modification, it should be correctly pointing to the public folder, though. I see there is an "output_dir" "option" mentioned in the readme, which perhaps is not configured to go to public by default, but I don't know how to access that option or where to write that instruction, if that even is the issue.

I am going to move on and look for other ways to deploy my site for now. Thanks nonetheless for the tool!

[gl326]

I was able to fix this... the issue was that Github has an automatically-generated deployment action which can't be modified or deleted and it was overriding the provided deployment action. I had to add an empty file called .nojekyll to my repository root for it to skip building jekyll and instead deploy the artifact generated by zola.

This is super annoying that it took me so long to figure out. I would definitely recommend you add this instruction to your readme to save future headaches for other newbies like me.

[gl326]

OK, after more errors and debugging I worked out what the readme meant by configuring the repo setting to use Github Actions.

I know this is probably very clear to experienced web developers, but as a newbie, I didn't realize this was guidance to set a specific dropdown in a specific location to a specific setting. There are many checkboxes, permissions and security settings which I enabled/verified to make sure my Github actions were being processed and would work, and I thought the readme guidance was broadly referring to any/all of these, not the specific "Source" setting which defaults to "Deploy from a branch" (and to a newbie doesn't look relevant at all to Github Actions, because I didn't know that was an option in that dropdown).

I think the Readme would greatly benefit from a little more guidance on exactly what the Settings > Pages area should look like.

I'm re-opening the issue only because I feel confident this is a good suggestion to make the guide a little clearer. You can close it without fixing if you disagree though. I've just been face-down trying to debug so many new things in the lst couple days and would love to spare future developers the same issues.