Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Problems encountered while following the "Getting Started" documentation #466
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
So I load http://127.0.0.1:1111 and it says:
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.
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
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
Problem 3: Running
"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.
It is! Thanks a lot for that.
Will do. Edit: 5be4b82
Not really possible :/ A message could tell users beforehand to lookup the README of the theme which should have the information to get started
This error message does need to be improved.
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?
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:
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:
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:
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.
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 :/
Made a topic about better docs / zola init on the forum: https://zola.discourse.group/t/improve-documentation-first-time-experience/24