I just went through process of migrating my small corporate site from another static CMS over to Hugo. Overall the process worked well but I had two stumbling points.
I was able to clear both of these up with more reading of the documentation. But I think first-time users would be happier if your quick start addressed these issues:
The first challenge was running the site without the buildDrafts flag set. I followed the instructions, launched hugo server and was surprised to find there was no content. So I started troubleshooting. Was the web server really responding? Was there an error message? I finally turned back to the documentation to see what I missed. It never occurred to me that the first step explaining how to serve the content wouldn’t actually serve the content.
I would have preferred that first step include the buildDraft flag and just worked. The startup process is simpler and it’s still pretty obvious what the flag does.
Except that it still didn’t display the content. Because now I needed to download a layout or theme. Once again I started troubleshooting. What’s in the HTML source? Is there an error message? Drafts? No drafts?
I’m not sure what the implications of releasing this with a minimal layout or theme are. I just know that it was frustrating to once again be told to do something and and read, “gotcha, still need to do more”. And while creating the layout wasn’t a big deal … I wasn’t falling into the pit of success. It seems like it ships partially broken out of the box. At the very least the quick start should not tell me to run the server until it’s actually going to show content.
At this point I was wondering how hard the rest of it was going to be if getting started was this hard. And I’m happy to report the rest of it really, really easy. I got the site running fairly quick and was easily able to copy all my content over and apply my old layout.
I freely admit that better reading of the getting started guide could have sped things up. But I think there’s an opportunity to make that less necessary and I hope you’ll consider it.
And thanks for all your work on this. It’s been a great product so far.
That said, you specifically call out the Quick Start, which has only been slightly updated in the new docs to reflect the changes Hugo has undergone since v0.15 (the time at which the original QS was written). I am planning on a complete reworking of the QS as well:
You’ll notice the connection with conversations regarding a new default theme, which I think is a great idea for introducing concepts.
All feedback on the new docs site is welcomed and appreciated.
we’re a small web agency migrating to Hugo as we have done most of our prototyping in static html anyway before converting it to some other CMS. We like the appeal, but sadly I have to agree with @graz.
I have taken some time to go through the current WIP version of the new Hugo website & I mostly have a single problem - while it may have been visually improved, the content very much remains the same. Creating new themes section is confusing & severely lacking information, especially since adoption of Hugo & similar static site generators is coming from a development World.
I really like the concept of Hugo & would love to help out in any way, but with about half of my website running & half of it hitting 404 pages, I don’t think I have the skills yet. But if you need an insight into a mentality of a Hugo beginner, we can schedule some time to work it out.
@morpheus7 Thank you for the feedback. The thing I find interesting is that you mention the content hasn’t changed much between the two sites, when I think the content has changed considerably. The content and site structure is also quite different. Interestingly, the design portion is currently underway thanks to @budparr 's generosity.
My main point is twofold:
Would you mind sharing some of the areas of Hugo you found especially difficult, counterintuitive, etc? It seems you found the “themes” section to be especially lacking, yes?
If you point me to a repo for your site, maybe I can help you with the 404s
Sorry, I didn’t mean to offend, I skimmed it pretty fast and maybe on the pages where not much has changed.
When I started yesterday, I had a million questions, now that number dropped by about half
Here’s a few that come to mind:
I’d like to see some best practice examples for config.toml, that list all the recommended formats & best practices (e.g. when setting a languageCode, should you use a “en-US” or “en” only)
same with some kind of default theme, even if it’s not included in the distributed version as best practice.
I think this Layouts 101 could be almost enough, if it would display where the template for single page, homepage, type pages is located
(e.g. when hitting example.com/blog/some-blog/ it would say "This template is located at themes/default-theme/layouts/_default/single.html)
Right now, the information stream - aside from this beautiful forum - is rather dry, there are no books yet or official video channels for Hugo, which I think it’s a shame (while fully realizing how much work it takes to keep one).
I couldn’t agree more. @sethm has talked about creating a default theme as well, and I would love to have this wedded to the new Quick Start so that people can get up and running and introduced to Hugo concepts as fast as humanly possible…
I think @michael_henderson has helped me with some 404s as well in the past
I edited my previous response a little to give some more info:
I’d have it under site config, more then multilingual maybe. I think it’s one of the first things you set, as it is positioned next to title, which everybody messes with straight away.
I’m actually using the types to have a multilanguage site on one domain as Hugo beautifully has nested types that go one level deep. So, my default language is Slovene, and then my top level “type” is en to get the en/ for english sites in URLs.
I usually Google the language codes anyway, but I’ve seen a helpful link somewhere on this site that helped you verify yours.
So far I have hardcoded the languages in the index templates, might clean it up in some nicer way one day. Until then, $h!t works.
I’m all for a default theme too @rdwatters. But my desires extend beyond allowing a quick start: I’d love a default theme to showcase best Hugo theming practices. As it stands there are no standards set — that’s not a negative comment; by it I mean that 10 different themes do the same thing 10 different ways. So for those who want to follow best practices but are new to Hugo or new to coding, how do they know what the best practices are. Who’s right? Who’s wrong? What do the Hugo Crew themselves think? We don’t know so we come here and ask. A default theme would be the best documentation ever.
I’ve been a long-time fan of Hugo — since v10 I think —though from a far. I dive in on a new project and I know I want to use Hugo because of [add all Hugo’s benefits here] but there’s simply no benchmark theme standards or default best practices so you’re left wading through dozens of different themes, forum posts, and more and left to decide for yourself. But I’m no an expert or even a real coder: I know enough though to appreciate and want to use Hugo.
I believe a default, benchmark-standards theme would solve a bazillion problems for everyone, especially new Hugo users who could use it as benchmark to guide /build their own.
Wow: I just found @budparr’s brilliant Ananke theme which does exactly what my last post was asking for, and much more.
The intent of this theme is to provide a solid starting place for Hugo sites with basic features and include best practices for performance, accessibility, and rapid development.
A bazillion thanks for your efforts Bud and I think everyone should head over and Star Ananke on Github.
*If anyone’s working on an unstyled fork of Ananke please let me know.
I appreciate your feedback. And you’re absolutely right: @budparr’s theme is as awesome as the rest of his work (he also did all the design on the new docs site, temporarily at https://hugodocs.info). My plan is to rewrite the Quick Start with Ananke as the example and also include some best practices (e.g., how to overwrite themes, why you should use submodules rather than git clone, etc). Just got back from a weeklong conference; hopefully I can start it soon:)
