Docs should have "Quickstart" section.

[ralfbiedert]

For someone who never used Zola, it takes a few tries to make it work.

There should be a quickstart page under https://www.getzola.org/documentation, that outlines these steps:

• Install zola
• Run zola init
• Clone theme
• create _index.md
• Add +++ ... +++ hello world.
• Run zola serve

Ideally step 3 (clone theme) should be possible to omit and still get a very basic result.

[Keats]

Agreed, that's something I hope will come through user contribution as it already came up in #466
The only think I would change is de-emphasize themes as it really has some issues that are not trivial to fix vs just having the templates/css in the normal folders (#324 and #361)

[Bridouz]

How about including a minimal starter theme like the one you're using for your blog ?

Zola's theming process could be scary for some users :)

[Keats]

Most of my Zola sites are not blogs though

[Bridouz]

Then a global starter theme :)

[Keats]

Made an issue about that in the forum: https://zola.discourse.group/t/improve-documentation-first-time-experience/24

Then a global starter theme :)

Not as easy as it sounds :p

[radio-alice]

Hey guys, over the past few days I've taught myself zola to use for my B.A. thesis and found myself really wanting a more helpful quickstart guide. I def don't understand everything zola can do, but feel like I could write a pretty decent (basic) quickstart– what can I do to help here?

[Keats]

@radio-alice Amazing!

I think the docs are missing a Quickstart page in the Getting started section (which would be just before https://www.getzola.org/documentation/getting-started/installation/ in the side menu) - basically the first page of the docs you land onto.
The one from Jekyll (https://jekyllrb.com/docs/) is a bit too short to be useful imo and the one from Hugo (https://gohugo.io/getting-started/quick-start/) is very oriented towards themes.

We also have to consider some default templates (#672) if that helps people getting started, eg rendering the content but with a big message indicating this is a default template and how to change it.

Before writing the quickstart, I think we need to consider what are the issues new users encounter and see if we can fix them in zola itself, so users don't need a quickstart guide.

Did you have any particular issue when you started using Zola?

[pianomanfrazier]

As a beginner I am struggling to get a first working example. I am very familiar with Hugo and I am trying out Zola. I ran zola init and then followed the directions for the Even theme and I got the following error:

$ zola serve
Building site...
-> Creating 1 pages (0 orphan), 0 sections, and processing 0 images
Error: Failed to render page 'zola-blog/content/first_post.md'
Reason: Failed to render 'even/templates/page.html'
Reason: `get_taxonomy_url` received an unknown taxonomy as kind: tags

I am not sure how to fix the error. I have the taxonomy tags defined in my config.toml and then in /content/first_post.md I define some tags.

It would be nice to have a simple github repo to clone just to play with, with or without a theme.

Using zola 0.7.0

[jhereth]

@pianomanfrazier Could you please share/gist your config.toml and first_post.md? Probably just a small syntax issue.

[Keats]

It would be nice to have a simple github repo to clone just to play with, with or without a theme.

You should be able to clone the Even theme repo, it is a site itself.
From the error message it seems there is a misconfiguration in config.toml maybe?

[pianomanfrazier]

Here is my gist. https://gist.github.com/pianomanfrazier/9f76f42ee77f544bbb6ddfa11a5ad255
I figured it out. In the meta data I put:

+++
[taxonomies]
tags = ['python', 'stuff']
+++
I got rid of the `[taxonomies]` in the markdown metadata and it worked.

[jhereth]

@pianomanfrazier As far as I can see from your examples it WAS correct. Without [taxonomies] zola shouldn't pick up the tags as tags (i.e. the page won't appear on the corresponding tag page).

If the issue is solved, great. If not we should move this discussion to a new issue (it's related but not strictly about a Quickstart in the docs).

[radio-alice]

Maybe it was because I didn't want to use a theme (project had specific visual goals), or maybe this is more an issue with Tera (or the fact that this is the first static site gen I've used), but here are things that took me too long to figure out:

• {{ page.content | safe }} is how one accesses the content from your .md files
• weight trait is how you set custom page order (I assumed it calculated page size and ordered by that even though that wouldn't really make sense)
• use config.base_url in templates to manage different paths for dev vs build
• and this is a more specific case but info about splitting content into columns at a certain string would have been helpful

None of these are completely impossible to figure out, just info to cover in a quickstart that I feel would be helpful to get people up and running quickly.

[Keats]

@pianomanfrazier can you open an issue on the even repo?

@radio-alice

use config.base_url in templates to manage different paths for dev vs build

You actually want to use the get_url function (https://www.getzola.org/documentation/templates/overview/#get-url) most of the time

and this is a more specific case but info about splitting content into columns at a certain string would have been helpful

Definitely too specific for the quickstart.

The other 2 points are very valid though, maybe it could include customising the page and section template for example?

[Hugo-Trentesaux]

I made a quickstart draft available on my blog (recently migrated from pelican to zola) https://blog.trentesaux.fr/informatique/en/quickstart-zola/
And on my gitea : https://git.42l.fr/HugoTrentesaux/zola-quickstart

[michael-conrad]

The links on the following blog posting don't work:

I made a quickstart draft available on my blog (recently migrated from pelican to zola) https://blog.trentesaux.fr/informatique/en/quickstart-zola/
And on my gitea : https://git.42l.fr/HugoTrentesaux/zola-quickstart

[Hugo-Trentesaux]

@michael-conrad you're right. Thanks for telling me. Should be fixed now.

[Keats]

There is a quickstart guide now.