Let me start by saying I feel a little bit uncomfortable about posting this because folks seem to be very proud of the documentation available given the “How to Request Help” announcement that I got when I signed into this forum. My intention is to try to suggest improvements for folks who are trying to get up to speed quickly and like to learn by poking initially, before spending a lot of time on the docs.
I have a site (mostly blog, partly static pages and photography) which I moved from WordPress to a Python-based static generator (Acrylamid) which has been discontinued. After moving to a new computer I was frustrated at the setup because I was never able to get it working easily on Windows. I spend time on Windows, Mac, and occasionally Linux, and want to be able to publish from any of them. Hugo seems to fit the bill with the platform support and is unlikely to be discontinued in the short/medium term, so I have to decided to move to it.
I went straight to the Quick Start as my starting point because I’ve worked with these kind of tools before. I copied over my existing content in markdown format, and lo and behold it just published. To be more accurate it was published, but my post list and recent posts didn’t display - just the couple of posts in the /posts directory.
My problem, and the thing that I want to point out, is that I felt that I was left a little high and dry. The remainder of the Getting Started section at the time of writing reads like separate articles for the most part, so the Quick Start doesn’t lead you towards a progressive understanding of Hugo.
If someone is looking at this area of the docs it would be great if:
- A simpler theme than ananke was used. Ideally, it would be built around learning the product as much as being theme someone could run on their site. It took me longer than expected to reverse engineer what was going on so that I could do my copy and paste of HTML from my old Jinja2 templates.
- The quick start continued by doing a tour of the theme with suggested modifications that added some common features.
- Template language and look up rules were highlighted in the context of the quick start example.
- More examples of how image and video content should be added to a site is presented.
This might seem like a lot to include in a quick start, but I think that it can be covered fairly tersely and provide a much better experience for the more experienced developer with zero Go Templates or Hugo experience.
Thanks for reading!
-Brian