hugoDocs
hugoDocs copied to clipboard
gohugoio
Quickstart is too short
In my opinion, the Quickstart should at the very least cover:
- how to include a picture (website banner and picture inside a page),
- how to include a menu,
- how to make a difference between a post, to be listed inversely chronologically on the homepage, and a more permanent document, whose promotion to the homepage or not won't depend of the date it was published.
Explaining how to make a multilingual site, with several linguistic versions of a same page would also be appreciated.
how to include a picture (website banner and picture inside a page)
This depends on the theme.
how to include a menu
This depends on the theme.
how to make a difference between a post, to be listed inversely chronologically on the homepage, and a more permanent document, whose promotion to the homepage or not won't depend of the date it was published.
This depends on the theme.
Explaining how to make a multilingual site, with several linguistic versions of a same page would also be appreciated.
See https://gohugo.io/content-management/multilingual/. This example site may be helpful:
git clone https://github.com/jmooring/hugo-multilingual-example
cd hugo-multilingual-example
hugo server
Thank you for this link. A QuickStart is not supposed to present all options, but one simple option that works. Since you chose Ananke as theme example, you should go on with this example. To my mind, at the end of the QuickStart, the reader should have a small website that works and looks like a real one: a site with 0 picture and 0 menu is frustrating. An alternative would be to direct the reader to one page explaining the basic of Ananke (how to add a picture, a menu, a post, a permanent page) but I don't know such a page (and the installation instructions of Ananke are not for newbies: they assume that the reader already has an account and a project on GitHub without saying it, not to speak of explaining what GitHub is for.).
I agree that the starting documentation is lacking. Or rather, there is quite a gap between the quickstart, and the next stage, this presents not so much a learning curve, as a learning cliff. There's also issues around how the quickstart docs don't have enough of a why, just a "run these commands and away you go" mentality.
One part of this. We initialise a git repo. Great. Why? Is this just so we can git submodule the themes? or is the intention that using git version control for a site is encouraged?
The moment a user wants to do something more advanced, such as adding a picture to a post, things get very complicated and the documentation is woefully lacking. There's lots of info on short codes, but unless it's very well hidden, no information on WHERE to use shortcodes. "Use this bit of code to do x" great, where do I use that? is it in my markdown? in a config somewhere?
One particular area I found this incredibly frustrating is with the image processing stuff. Even 3rd party blog posts that provide examples of code to use, don't cover where to actually use this. It's very off putting on what otherwise looks like a great project.
And to preempt the "It's open source, you're welcome to contribute new documentation" anyone who is struggling with poor quickstart and beginner documentation is not going to know enough about the project to be able to meaningfully contribute something better. The best we can do is offer feedback that as newcomers to hugo, there are issues with the docs that make it hard to get started.
I'd like to pile on here. The issues start right from the installation instructions. Debian installation simply tells you to 'apt install hugo'. Doesn't tell you that on Ubuntu 22.04 LTS that installs a version that is so out of date that it isn't even enough to continue with the Quick Start Guide ('apt install hugo' on 22.04 LTS installs hugo version v0.123.7; quick start requires v0.128.0 or later).
Ok so I need to install a different version.... how? Well there is: "You can also download Debian packages from the latest release page." at the end of the debian installation instructions...... Great.... which one do I install?
