I just started using Hugo, but boy, are the docs bad... and I mean REAL BAD. It took me an HOUR to setup a theme. Then another 30 mins to realize I've set up the theme the wrong way, using a git submodule, instead of a go module. Then installation of the go module itself took another 30 mins of debugging, because nothing was working out of the box. And nowhere in the documentations are things explained for novices. The docs are written in a way that assumes you already know Hugo's ins and outs. uh... At this point, I would've been better off with a WordPress install that takes 5 minutes to do manually.
Had a similar experience, so I decided today to write a Github action[1] that automatically takes the contents of an Obsidian[2] vault, generates static content with Hugo and publishes it on Github pages. Hopefully I have documented the steps clearly [3].
After initial setup, the idea is you can edit a blog on any machine (not requiring Hugo locally). Just check out a repository, make changes and do a `git push`. All the hard work is done in a Github runner.
I wanted a simple way to be able to cut and paste screenshots into Markdown and generate a static site. Obsidian is both an excellent note taking tool and editor, so it seemed appropriate. Of course the markdown files can be edited with any editor.
Hugo is very opinionated. But that opinion it has isn't very well communicated, and I myself don't think I fully understand it enough to write docs on it.
Hugo has opinions on where files should be, how it should be transformed into pages. How those pages should be organized (ie: Taxonomies), and how users and template writers should be able to customize these elements to generate very different web pages.
------------
I do wonder if "Document Hugo" is the wrong approach, but instead the proper thing that needs to happen is "Create Beginner-Hugo-Template" and document that instead.
Then, "Create Intemediate-Hugo-Template" and document how various things you add to these Templates can improve a blog, or book, or various different webpage "ideas".
Hugo is great but the learning curve is madness. I've used it twice with a couple years in-between, and succeeded, but it's very annoying to have 1-3 hours of failure before you see anything useful.
Add theme, follow tutorial, somehow blows up, need to figure out exactly where to put what, round and round then find a tiny wedge that works and just expand that until I have something that does what I need. But once it's set up it's really fast and you can iterate on your pages very nicely. No "tons of imports" that I needed with Jekyll.
This past weekend I spent most of a day playing with various simple SSGs with the target of migrating my Hugo blog to something simpler. This was after I spent a couple hours in Hugo trying to generate a page with just simple links to all the blog posts.
Years ago I rewrote our entire company website, including hundreds of blog posts an articles, as well as marketing stuff, in Pelican in a day or two.
When I set up my Hugo site originally, I think I spent some time munging around and eventually got it to work, but that was years ago and everything I learned is lost. So I need something dead simple. But not, unfortunately, so minimal as gostatic.
Thanks for the pointer, I hadn't heard of that one. I'd put it in the same department as "gostatic" as being too minimal, unless you want to build the templates yourself. gostatic allowed me to have tags where from a quick look cobalt does not.
edit: Forgot to mention: The install option seems to be broken, you have to go into "Reference" to the install guide to find an alternative.
Hugo is really nice once you spend some time learning the templating system and how the variables get set up. It does have a learning curve at first, but I don't find any of the alternatives to be as compelling as hugo once you're up and running.
I use and love Lektor! Built-in CMS, simple templating system, and a lot of flexibility if you want it (but with a great Quickstart option).
Even as a dummy Product Manager, I've been able to write two plugins[0] for it over the last couple weeks (I'm one of the many laid off folks with a wee bit of extra time), and it's been a joy. Definitely frustrating moments — the docs could be better — but the maintainers have been super kind and helpful. It'd definitely benefit from a larger, more active community. Join us!
WordPress. I hate its guts, but my god does it just work. Or I'm just going to give up and use squarespace or webflow, or something like that. I've got a full time job, managing this is not worth the mental energy it takes to learn all it's quirks.
I like Sphinx [0] with the MyST Markdown syntax [1]. There is a related project, Myst NB [2], which enables including Jupyter notebooks in your site. There is also a plugin for blogging [3].
Thanks for this! One of my frustration with tools nowadays is that they aim to be so "user friendly" that actually make things complicated and thus understanding how something works, which allows one to be more productive with a tool, is hidden under tons of layers of complexity and simplistic "getting started" that can indeed make an amazing looking website with 1 command, but from there on, trying to figure out _how_ that amazing website works and how can I adapt it for my need is a rough journey!
Exactly. I ran into this when trying to set up Hugo, and wrote for myself a notes page with the following:
# What is Hugo?
`hugo` is a program that takes some .md files (ideally, conforming to a certain directory structure) and creates some .html and .xml files (conforming to another directory structure).
This is the minimal command:
# Create input directory structure to silence warnings
mkdir content layouts{,/tags,/categories}
touch layouts/home.html layouts/{categories,tags}/list.html
# Run hugo: creates public/ and resources/
hugo
…and building from there.
If you read the Hugo documentation, it talks about all kinds of stuff but doesn't explain anything from the bottom up: apparently the usual way is to start with a pre-existing theme or site as template and edit it, but that's not explained anywhere either. After you eventually learn exactly what Hugo is, it becomes ok to use.
That's not Hugo's problem, that's a problem with Hugo's docs. Something that pretty much all projects, and most big companies, struggle with.
There's very few documentation experts out there. Those who write the docs are either devs who write broken English, or English majors who don't understand a lot of the tech stack. In either case, they usually miss the target persona, and what are the reader's needs.
I'm not a hugo expert, but the two main things that I needed were:
1. An understanding of what variables are available, and where. Hugo nicely collects a lot of useful info but it is difficult to know what it all is and where it is. https://gohugo.io/variables/page/ is a good start but it is difficult to know how these are populated.
2. Hugo is implemented in Go, so under the hood everything is strongly typed. But the Hugo documentation throws that all away and presents the dynamically-typed interface that Go's html templates provides. The problem is, figuring out what anything can do is made very difficult by that. So, ok, I have a .Content or a .Data for this page... but what is that? Is it a string? Is it an object? If so, what can I do with it? I have to experiment to find out, or grep over a couple of templates to figure it out.
Honestly if I had to make just one suggestion to the Hugo docs team, it would be, strongly type your entire documentation suite. Tell me what the type of everything is, and the resulting methods/functions I can use it with. (If it's an interface, fine, I don't mean all the maximally static types necessarily.) That wouldn't fix everything, but it would fix the frustration I experience of visiting https://gohugo.io/variables/page/ and still wondering what any of that stuff actually is.
That's pretty much the space Wordpress thrives in, isn't it?
How shit the product is for Wordpress is a matter of debate, but the documentation and ecosystem around it is robust enough to make it fairly easy to hack and use/abuse to do what you want it to.
This is true. Docs, re not necessarily considered important features of the product itself but they make a huge difference.
Other things that I pay attention to are built-in integrations with other tools, the ability to import and export data, familiarity to users, similarity to existing tools, tutorials that leave users confident, and documentation with examples of use cases are all similar factors.
I'd even take this hot take up a few more degrees and say the docs quality not only represents the product quality, but also validates it. In other words, you can't know whether your product has a chance of being good unless you're _able_ to write good docs for it.
> ...If you notice that the docs are bad, the product is bad...
This right here is so correct! Given the option of 2 (or more) products/services, in my mind, the one with the best documentaiton wins...because it usually means it is the option that is more easy to implement...or at least i can research how to make it the esier option to implement, etc. Good docs for the win!
I've been blessed to have started my career at a place where the docs were surprisingly comprehensive, and I've done my best to carry that torch. My old DevOps team wouldn't have it any other way.
I got a thumbs up just a few days ago on a Confluence doc I wrote months ago explaining at a very high level what two legacy parts of our software does, from a new hire I have never met or spoken to. That really made my day.
I plan to record a small (4?) series of videos about starting with Hugo from scratch. Would love to hear any pain points you specifically think need to be addressed.
Being a video is a pain point for me. I much prefer a useful text tutorial with code I can copy, etc. But I don't want to be a choosy beggar so you do you :)
Hmm, that sounds good but when I go to the homepage it gives me buttons for learn more and download, neither of which work and the focus is all messed up. I know it's probably not the CMS part that's broken but if the website for a website builder doesn't work it doesn't inspire confidence.
Yes, I also found it difficult to understand how Hugo worked internally.
If you’re ok with NPM, Metalsmith is a trivially simple static site generator, where you just write JavaScript code to customize it (and of course you can plug in templating tools). If you don’t like NPM, but like JS/TS, I started a port/rewrite of Metalsmith for Deno, I can share if anyone’s interested.
Metalsmith is cool! I hadn't heard of it til now but it looks sweet.
I actually made something similar except mine isn't designed for static sites specifically. It just takes markdown, parses it into HTML (with code highlighting of course) and stores the html and frontmatter in an in memory sqlite database that gets rebuilt each time you save. Not the most efficient choice, but it makes plugging it into any front end framework like nuxt or next or svelte really easy, particularly if they have server side rendering. I guess it's almost halfway between this and PicoCMS. And you get full text search.
Although I now see that I only documented in-code. It’s very similar to Metalsmith, except based on Deno, in TypeScript, async, and standarized on RegExp instead of a grab bag of globbing libraries.
Love Hugo. Been using Hugo for quite some time. But I agree with the author that there is a "Running hugo server -D now!!! ... Where is it!!!!" problem when following the tutorial.
Hugo has many "magic" based on names, "index.md" vs "_index.md", template look up hierarchy, global variables and functions (sometimes capitalized, sometimes not; some are behind a context, some are not), etc. It's hard to tell what name is required, what is configurable, and what is just accident, until you've delved into the detailed documentation. And to make the matter more complicated, themes sometimes use name magics, too.
I also hope that Hugo can just allow piping stuff through external programs in its templates. Right now, Hugo provides a pretty large number of APIs on resource transformation, regexes, string manipulation, and hell, you can even download stuff in templates. But to be honest, it's way easier to just write a shell script.
If I were to make my own static site generator, I think I'd probably opt for less flexibility, and simpler logic, especially with regard to what file ends up where. Let the generator handle the basic MD->HTML transformation, the skeleton of the site, producing feeds and metadata. And let external programs handle everything else.
Classy and direct, I like it. Serifed fonts always bring me back to the days where I would sit in the old mahogany chairs of my university library and just read whatever came to mind.
If I had more free time I would love to build a similar website for Nicholas Rescher's approach to process philosophy, that's my particular hobby horse, Rescher and maybe a little Charles Hartshorne for flavor.
I'm a little unsure what license I can slap on the repository, since even though I've written all the code, the content (text) was written by 3 philosophy professors & the guest essays were by other authors.
While they are currently working on making this an Open Access Textbook I'm unsure what license I am allowed to attach to it. Perhaps when they coordinate with their publisher they will know better - I've been meaning to ask.
This is exactly why I gave up on Hugo and LOVE mkdocs-material. It has such a simple setup and such a good out of the box experience that you can start with it literally in minutes. I was so surprised that the second command is serve and you actually get a working site, which you can iterate and fine-tune later.
I had the exact same experience. Everything that sucked about hugo that I discovered only after a week of trying to do something simple with it was fixed with mkdocs.
It made me appreciate that static site generators look easy up front but are actually a huge amount of work to do right.
I also experienced this when trying out Hugo. I think the issue is when you go into it with the expectation of building a simple website that you build from scratch, rather than a pre-built theme. Personally, I found that Zola was much simpler for starting from scratch.
I tried both and ended up with WordPress of all things. I really don't blog and after a year without making a post I couldn't figure out my own Hugo site. I had also changed computers and my site wouldn't build anymore. I think Hugo is fantastic but probably best for regularly bloggers.
If all you care about is maintaining a simple blog or personal site I recommend just writing your own static site generator. Seriously, it takes probably an hour of work and ~100 lines of code or less and you can customize it however you want.
Ive used mkdocs at work, and Hugo for my personal blogs and sites (I recently created https://cyphersrd.quest using Hugo).
I will say at first its always takes a second to remember how all the folders nad files interplay, especially the `_index.md` file, but after that its super clean.
I tend to find a theme that I like that is MIT or ISC licensed, and then modify it from there to my liking. Like for the site I linked, I started with `hugo-book` but didn't like some of the coloring, so I transplanted a good chunk of Water.css into it and it looks good now.
I think thats mostly because the default setup and boilerplate make it seem that way.
You only really need a `config.{toml,yaml,json}` a `content` folder and a 1 file theme like the one in the article of this thread.
Everything else is just extras.
I will admit I am currently for fun working on my own static site generator, and its slowly getting pretty complex just implementing the basics. Which gives me a new appreciation for what Hugo is doing, and many other site generators.
The more generic and multi-featured you make it, the complexity just increases.
Going back to basics and having zero external dependencies is quite enjoyable. Understanding how Hugo templates, themes, and content all work together was more complicated than I originally expected, but they have build a good system. Hopefully this helps anyone looking to get started.
This is an excellent little website, I'm I work with a few guys who have been playing CS for ages and I bet they'll get a real kick out of Pure skill next time I see them at the office.
I am using hugo for several years now, so quite thankful for what it offers but I am slowly coming to the conclusion that i) you need to learn go to get the most out of it and ii) a "semi-dynamic" site that uses a simple sqlite backend might be a sweeter spot (for my needs) in terms of balancing simplicity, features and practicality.
I did't not find yet a replacement though. One reason is that I would love to continue having markdown as the main format for creating content but somehow that is orthogonal to having that markup stored in a db backend instead of the filesystem.
Out of curiosity, what do you need a database for? Could you just regenerate your static site when the database updates, thus allowing you to keep serving static HTML?
its various little annoyances: rebuilding a site can be tricky when you are on the move (say with a mobile device) and just want to add/edit a bit of content. or to give editing access to non-technical people. or the search capabilities that are more powerful with a db etc.
it feels that between the spartan austerity of an SSG and an overengineered full-blown database-backed CMS there might be some intermediate option. or maybe not :-)
Oh, those are interesting issues. I've had a similar hankering but for me it's 99% just because I want a nice comments system. I've toyed with the idea of taking a project like Issi and rolling up a SaaS based on it which basically provides an SQLite comments system. Paste one line of JavaScript into the page, and boom.
I've always found Hugo easy to get running. Compared to Jekyll, Hugo was always much easier as Jekyll always seemed to throw up some Ruby or Bundler issue every time you went back to it.
I've built a lot of Hugo sites and templates, I have 10+ open source themes at https://github.com/zerostaticthemes so here are my main observations of Hugo
* The docs do need a lot of work, but the forums and stack overflow are pretty reliable sources with Hugo having enough critical mass to get answers for even obscure errors and questions.
* Hugos big problem is the Go templating language. It's arcane and unintuitive. Even after years I still find myself forgetting how to do and or conditionals.
* Hugos template lookup order is opinionated but one of it's strengths.
* Hugos . context is opinionated but also one of it's strengths.
If you are looking for a minimal SSG then I think it's important that it's HTML based (so no Nextjs or Gatsby) - Jekyll, Hugo and 11ty are the main options in this space but there is also a wave of new options which seem worth considering. There is a great list of ssgs over at www.staticgen.com if you want to browse the up and comers.
I recently started a blog again with Hugo and I like how you can easily use a github workflow to build and deploy it. This way you can even just use github in your browser to publish.
It took me an afternoon to glue together my own DIY SSG with all the features I wanted. I did that after a previous SSG didn't do what I wanted and I didn't know how to fix it since I don't know ruby.
An SSG especially is such a low-risk project.
Probably the most carefree code you could possibly write.
Hugo is not made for minimum viable blogs. Its advantage in performance only becomes important for bigger websites or blogs with thousands of articles. But especially for bigger websites it should be possible to auto-generate a good archive. However the developers of Hugo stubbornly refuse to fix this very important 8 year old issue: https://github.com/gohugoio/hugo/issues/448
That is quite unfortunate, because it makes Hugo "the worlds fastest framework for building huge websites without a useful archive".
It doesn't sound like the Hugo developer (bep) "stubbornly refuses" to fix that issue. It's on the roadmap, after all. Rather, it sounds like it's simply not a high priority task, and other things have taken up his time. It is a free product, after all.
It's on the roadmap since 8 years. But the problem I have with this free kind of software is that they claim on their website " The world's fastest framework for websites". That generates some expectations. They don't claim "the world's slowest hobby project, written by people in their spare time for no money." So it shouldn't be a surprise that people get disappointed, if important features are missing from "the world's fastest framework".
I tried to make a minimal Hugo site just a few days ago. There is a quickstart on their website, which I followed, and it seemed to work as expected. Did I get lucky? Am I in for a world of pain as I try to go beyond the extremely minimal site I have now?
You can just write HTML too. It is much simpler, easier to maintain, and more secure (using a real webserver). Make .html files, open them in a text editor, type in the HTML. Here, I'll make an example like the minimum viable hugo.
$ sudo apt get install nginx
<html><head><title>Lorem ipsum dolor sit amet</title></head><body><h1>Lorem ipsum dolor sit amet</h1></body></html>
And now save it as index.html in the www directory that installing nginx creates. Check it out at http://127.0.0.1/ . Go to your router and forward port 80 to the IP address of the computer running nginx to make it public.
I think the intent of OP was to help people get setup with Hugo so your comment is pretty off topic. Yes you could set up php, elm, a full lamp stack, rails, heck you dont even need nginx to serve a static .html file but none of that will help someone get setup with Hugo if that's what they want to use for static site generation.
I'm not being sarcastic. It is what I've done for 20+ years (although I only switched from thttpd to nginx in ~2010). The linked article does not really teach you how to use hugo. It just shows how to generate a single page, and there are far better ways to do that.
And like others have said, nginx comes with server side includes built in. It's the perfect amount of dynamic templating power with the minimal attack surface. Before anyone jumps in with, "but I can deploy (or other cargo cult terms) my website to a CDN if I use Hugo for templating." I question the utility and complexity of bringing in a CDN in this, minimum viable context or any personal website context.
I can deploy [sic] my website to a static file serving service for virtually free (e.g. S3, GitHub Pages, Azure Static Sites, etc.) without having a CDN and without having to worry about renewing SSL certs, managing a full linux instance or container, patching the web server when stuff gets hacked, doing maintenance, etc.
There's a ton of value in 'just static pages', and if you do more than 1, not writing your own HTML is pretty great.
HTML files can't reuse anything, HTML is a pretty bad verbose language, it is hard to keep indexes and links up to date when you change your site, and well, a lot of other reasons that I didn't think about because I gave-up on that in the 90's.
because writing HTML manually is fucking terrible compared to authoring markdown. We (i.e. everybody) are trying to improve things because they are bad.
I mean, I agree that incremental improvements are great but also I think your hyperbole is a bit of an overreaction. I use markdown and templates and Software people rightly prefer reuse and DRY principles but handwriting html is honestly only barely a notch more primitive.
Use SSI for header/footer/menu segments and write about 5 lines of bash and you've got all the site generator you need, too, and you can run your "generator" on basically any unixy machine without installing anything.
I find writing raw HTML for basic documents to be very fast and easy with a modern editor with hinting/autocomplete. Not any slower than Markdown, really.
As an oldie on the web, i would state that while it might be "ancient, arcane", but it was amazingly awesome at the time....and some still leverage this neat technology to great benefit. ;-)
Hugo builds and Jekyll builds are basically instantaneous even for really large websites. I mean less than one second. Like 30ms. You don't even see it happen. Migrating your manually crafted HTML pages to something other than NGINX or changing the theme or website is going to be such a pain in the ass you're going to wish you never thought of this "minimalist" way of doing it. If you look at the website of the guy above at superkuh.com it looks like shit (subjective, of course), doesn't even have a TLS certificate and above all would be an extreme pain to change the layout, design, deployment, etc. I don't even know what to say about this chart in his last post at http://erewhon.superkuh.com/pictures/blog-posts-vs-blog-post... although I must admit it's really funny.
Lovely. Gotta say, it's great that Hugo makes it easy for non devs to get going. But, if you wanna hack something together, the clay becomes too difficult to mold.
Yep, it's one reason why I wrote https://prose.sh -- a middleground between self-hosting a hugo site and copying markdown files to a managed blog site.
I swear folks. Take an hour and read the docs carefully. It’s not difficult to get a scratch site up and running with Hugo. The obsession with “mean time to dopamine” is exhausting.
I never had issues with Python versions - I occasionally had issues with newer Pelican versions (backward incompatibilities). It continues to work for me - been using it for over a decade.
