Problems encountered while following the "Getting Started" documentation

[jwatt]

The following is a description of a first time experience trying to set up Gutenberg as someone who's never used a static site generator before. I hope it's useful info to help smooth off some of the potential rough edges.

Walking through the "Getting Started" docs to experiment with setting up a site I get to the CLI usage and run gutenberg init guten-test. That initializes my site and ends with the message:

Web server is available at http://127.0.0.1:1111 Press Ctrl+C to stop

So I load http://127.0.0.1:1111 and it says:

Welcome to Gutenberg! You're seeing this page because we couldn't find a template to render. To modify this page, create a index.html file in the templates directory or install a theme. You can find what variables are available in this template in the documentation.

Problem 1: When I go to the install a theme page and follow through the instructions it simply details how to install a theme. "But where are the themes?", I think to myself. Hmm. Looking in the left-hand menu bar I see there was a themes Overview page that comes before the current page. Maybe that page has a link to the available themes...but no. More by luck that any intelligence I realize that there's a Themes link at the very top of the site linking to a separate section of the site outside the documentation with a list of available themes.

Suggestion 1: Include a link at the very start of the install a theme page linking to the available themes for dimwits like me.

Moving on.

Since the initial instructions on http://127.0.0.1:1111 say "create an index.html file or install a theme" (emphisis mine), and since I just want to get something working as fast as possible to play with, I opt to not create an index.html initially. Instead I just installing the 'hyde' theme, set the theme variable of the configuration file, and reload the site in my browser.

Problem 2: Now my website is blank, and the useful four lines of instructions that used to be displayed are gone. "Darnit", I think. "Did I not follow those instructions properly?" But since they're gone, I can't know. I also remember that there were further instructions and links but can't remember what they were.

Suggestion 2: Preserve the basic instructions displayed on initial load of http://127.0.0.1:1111. If that's not reliably possible because themes may "theme" that information page in a way that renders it unreadable, then change the instructions in some way so that people aren't guided into this trap.

In my case I tried moving the 'hyde' directory out of the site and reload to get the instructions back. That didn't work, so I terminated the server and restarted it with gutenberg serve.

Problem 3: Running gutenberg serve now gives me the error:

Building site... Error: No theme.toml file found. Are you in the right directory? Reason: No such file or directory (os error 2)

"Argh", I think. "What now?" It took me a while to realize that my problem is that I made the mistake of leaving config.toml still pointing to a theme called "hyde". I should have figured this out sooner, but the error message mislead me.

Suggestion 3: It would have been better if the error happened earlier, at the automatic rebuild of the site on detecting the theme directory change.

Suggestion 4: The error "Are you in the right directory?" implies that "I" am in an existing directory, but and the problem is simply that it doesn't contain a theme.toml file. In fact its problem is that the directory doesn't exist at all. Much more helpful would be the message 'No theme "hyde" found in the "themes" directory". I would have immediately realized my error rather than wondering things like "did the rebuild get a partial cache of the theme from somewhere that's now corrupt? Help!"

At this point I've got the http://127.0.0.1:1111 instructions back, and am now at the stage of trying to figure out how adding an "index.html file in the templates directory" will help me get a basic site showing. I suspect these instructions are incomplete, and from some jumping around the docs trying to figure things out I get the impression that I'm going to have to add an _index.md and/or an index.md (what's the difference isn't really explained) and maybe some other things. The issues described above will suffice for now though, and I can follow up with any further issues I have and suggestions later on assuming the above is helpful.

[Keats]

I hope it's useful info to help smooth off some of the potential rough edges.

It is! Thanks a lot for that.

Suggestion 1: Include a link at the very start of the install a theme page linking to the available themes for dimwits like me.

Will do. Edit: https://github.com/Keats/gutenberg/commit/5be4b822f9591d7d4a423ed1c014ff73862fc537

Suggestion 2

Not really possible :/ A message could tell users beforehand to lookup the README of the theme which should have the information to get started

It took me a while to realize that my problem is that I made the mistake of leaving config.toml still pointing to a theme called "hyde". I should have figured this out sooner, but the error message mislead me.

This error message does need to be improved.

Suggestion 3: It would have been better if the error happened earlier, at the automatic rebuild of the site on detecting the theme directory change.

Gutenberg doesn't watch the themes directory so that's not possible.

For the difference between index.md and _index.md, are https://www.getgutenberg.io/documentation/content/overview/ and https://www.getgutenberg.io/documentation/content/section/ not clear enough? Same question for the templates with https://www.getgutenberg.io/documentation/templates/overview/ and the following sections.

[Keats]

For the theme.toml error message: https://github.com/Keats/gutenberg/commit/44a33c020c7514c4e72c0feb300850a8f619ee29

[jwatt]

For the difference between index.md and _index.md, are https://www.getgutenberg.io/documentation/content/overview/ and https://www.getgutenberg.io/documentation/content/section/ not clear enough?

I'm afraid not. Not at all. :-(

Let me try and do some more out loud thinking through the eyes of someone new to this. So the Overview page says:

You might have noticed a file named _index.md in the example above. This file is used to store both metadata and content of the section itself and is not considered a page.

The content directory in this case has three sections: content, blog and landing. The content section has only one page, something.md

Okay, so _index.md stores metadata and content for the section (directory?). But wait, it's not a page? What does that mean? Does it mean that an index.html page will not be generated in the output folder for a directory containing an _index.md file? Does that mean I should ALSO have an index.md file in there if I want an index.html page to be generated for that dir? But then in what sense does the _index.md provide metadata for the section if there's also an index.md? And why not just make the index.md the place that the content and metadata is stored? And how do the two interact? And does this also mean that the metadata in the _index.md is used for something more than just generating the index.html? If so, what?

So far, so confusing.

Moving on to the Section page which says:

A section is created whenever a folder (or subfolder) in the content section contains an _index.md file. If a folder does not contain an _index.md file, no section will be created, but markdown files within that folder will still create pages (known as orphan pages).

Wait, this conflicts with what the Overview page said. It said "The content directory in this case has three sections" and named the "content" directory as one of those sections. But that directory didn't have an _index.md file, and the above text from the Section page says that to be a section it must contain an _index.md file. So which is it?

And what if I create an index.md file where I put links to the children pages in index.md's markdown? Are the pages still "orphan" pages now? What does that mean anyway?

The next paragraph goes on to say:

[lots of stuff.] your index.html template will then have access to that content and metadata.

This is the first hint of what might be going on here in the terminology and confusion. But it's only the slightest hint, not enough to make sense of things.

After several days on-and-off jumping around the docs and playing with a test site I'm starting to put the picture together, but it would be so much less painful if the concepts were laid out in a logical order. Also I still don't understand why the name of _index.md starts with an underscore.

I think the issue is that the docs assume a lot of prior knowledge both of templates and how static site generators work in general. That may be fine for anyone coming from another SSG, but it makes it really tough going for anyone interested in using Gutenberg as a first time SSG user.

I'd make concrete suggestions of how to improve the docs, but that's hard to do before understanding the concepts...and by the time I've understood the concepts I'll have lost my "new user" eyes. Hence all the out loud thinking above.

One thing that may be useful is to add a new "Basic concepts" page at the end of the Getting Started section with just enough of an overview for the sections that follow to make sense.

[jwatt]

And thanks for the changes you've already made in response to my feedback. :-)

[Keats]

Also I still don't understand why the name of _index.md starts with an underscore.

Mostly so it's at the top of the folder in case you have tons of posts.

I would love to get some help on documenting that as it is pretty clear to me :/ The idea is: in each folder (other than folder for local assets), you can have a file called _index.md which represents it and that allows you to set some metadata: sorting, pagination, anchor links etc. For example, my site has one section (other than the index one):blog which I'm only using to decide how to sort pages in it. All other .md files in that blog directory are pages of it.

[jwatt]

I'm happy to work on that, but probably won't get to it for a few weeks.

[Keats]

Made a topic about better docs / zola init on the forum: https://zola.discourse.group/t/improve-documentation-first-time-experience/24