If anyone is considering using Hugo, please account the tens of hours you will spend debugging its weirdness and magic. Yes, it's fast but it seems that ease-of-use was its lowest of the low priority. How variables work is impossible to understand. So is creating new layouts. Every change, however minor, involves fighting hard until I give up and settle for a hack.
The speed of generation doesn't seem much of an added advantage since you're gonna do it only once anyway. It's hard to know why would anyone make such weird design choices to solve a problem that has an easy, known solution. Am I trivializing? Maybe, but I know how much time I spend on rendering when I am working with Flask + Jinja and how it's 10x worse with Hugo.
Sadly, moving my blog way from Hugo would be too much work and I have to bear with it.
Hugo is way too complex for me as well. Not to mention the awful awful Go template engine.
I ended up writing my own static site generator which has a good chunk of the features of Hugo but focusing on ease of use rather than increasing the feature count.
> The speed of generation doesn't seem much of an added advantage since you're gonna do it only once anyway.
I have to disagree on that. My Pelican blog a few years back was taking several seconds to render vs milliseconds now and live reload is instant.
Not sure what you mean, but my blog is currently generated by Pelican, and on dev server mode, live reload is unnoticeably fast! (To be fair, my blog is also relatively tiny, so it may be a consequence of this).
On the other hand, would love to take a peek at your static site generator, if there is such a difference :)
The slow part was mostly syntax highlighting and that was at least 3 years ago. Looking at https://github.com/getpelican/pelican/issues/1326 it seems live reload as I mean it (without hard-refresh of the page) is only available through a plugin.
> On the other hand, would love to take a peek at your static site generator, if there is such a difference :)
Seconded. Cannot speak of other static site generators, as Hugo is the only I know, but it IS a pain to make anything that deviates from the golden path that's shown in the documentation.
Hugo has gotten very confusing as it has become more powerful. They are moving so fast and people are doing crazy stuff with it now! As the maintainer of a simple Hugo theme and a few simple blogs I can hardly keep up.
I have been following Hugo development, and I see that a lot of new features are getting added. But if it's something that I don't care about (i18n, SASS support, archetypes update, etc) I just ignore and don't use the new features.
I'm interested in knowing the overhead you are facing in keeping up. I just read the Release notes, and often find something I really wanted in the next update (if not everything in that update).
Overall Hugo development is quite conservative about introducing backward incompatible changes. They do happen, but very rarely (sign of progress). I remember the last time that happened about a year back when Page Bundles got introduced.
Because in my opinion, it starts to make sense if you understand what's going on behind the scenes with Go.
Hugo always struck me as an SSG for developers who want something in between the super-easy to use, with zero experience and, well, starting from scratch with every site.
Admittedly, even with a Golang background, I find there is quite a learning curve, so I wouldn't recommend it for anyone who is just trying to get their blog online.
This is not directed to me but I'd like to chime in and say that one doesn't need to know Go language to write Hugo templates. I appreciate Go Templates even without knowing Go.
It's quite simple:
- If you don't want to learn the templating for a static site generator, use one of the readymade themes.
- If you want to tinker with the themes or create your own themes, learn the templating language. There's no magic potion.
You don't. I use Hugo, and haven't touched a line of go code. For me, setting it up, using one of the available templates, with a few tweaks, seemed very easy. But I haven't used other static generators so I'm not sure how Hugo compares.
I recently looking into different static site generators and I chose Hugo in the end because I found their documentation to be very clear.
The Hugo framework can do a lot of things out of the box, without the need of plugins like most other frameworks. I saw this as an advantage, but I can understand you might want to go for something more simple if you don't need any of those features.
I know what you mean. I’ve been recently struggling with OpenGraph tags in Hugo. But there’s barely any documentation on how they work, so I had to hack something together that doesn’t work very well.
I’m looking into Jekyll, but can’t find any themes as minimalistic as my current Hugo theme[1]. Any recommendations for a simple theme that doesn’t look like the default?
Stick with Jekyll, its robust, has support with github pages, most number of themes for a static site generator, and the benefits you get from Hugo for performance are very small
What prevent Hugo from being supported by GitHub pages? I have never understood the "Jekyll integration" thing, you're just pushing static assets created by your static site generator to GitHub, so why would it be different from a generator to an other?
Github is based on ruby, so is jekyll, so its a frictionless setup that's free.
You can use netlify but there's more setup to that than github imo.
with github you can also have as many sites as you want, little unknown fact just make 100 organizations and you have 100 sites. Content is open to anyone though. But the option is still nice to have
Github runs Jekyll for you, that's all integration there is. Meaning you do not have to push the generated files to update a Jekyll page hosted on there, only the source files.
IMO, GZ compression is really something that should be handled by your webserver and most do it easily. There is a jekyll-gzip plugin if for some reason you need it.
The content is static, and webservers like nginx support service gzip compressed equivalents if it finds it alongside the uncompressed ones. Might as well do that compression once rather than multiple times.
If you're doing it just once, you can also realistically take the extra effort and use zopfli for further (albeit slower) compression.
Most of the major web server software caches the gzipped content. It only happens once.
Plus you can actually look at the files on the server without modification or piping them to gzip to check the files.
You can also elect not to gzip files smaller than MTU (1500 bytes) and stop wasting your and your client's time. Realistically it's often wasteful to gzip small files (below 5KB).
If you're worried about squeezing maximum compression out of your text files, then you're serving up too much stuff to clients anyway. You probably don't care about your users... just about your bloated page loading fast. Get rid of some ad garbage.
That is what GitLab Pages expects, and because I can control my own pipeline with GitLab I am able to support multiple file formats that GitHub would not be able to support. It doesn't get any simpler than the example I provided.
I'll try and contain my derision towards serious conversations about hosting performance-sensitive content on GitHub/GitLab Pages. As explained in a separate comment, gziping _everything_ is wasting CPU.
If you just gzip from nginx, have content caching enabled (why don't you with static content?), and set a minimum size for gzipping, you have the best possible scenario and take a small hit on first requests of files until server-restart/cache-expiration.
> tens of hours you will spend debugging its weirdness and magic.
That's a very surprising comment, without any detail. Can you elaborate on what you found surprising and magical?
> How variables work is impossible to understand. So is creating new layouts.
Again, some details would help understand the real problem.
[ It's agreed that you need to learn any new thing you'd like to use. ]
I have used Hugo for more than a year now, and I don't see any reason to move away from it, as it is awesome! Once you understand Go Templates (this is awesome too. Coming from Emacs-Lisp, I can associate the Go Template syntax with it in some ways :D).
> The speed of generation doesn't seem much of an added advantage since you're gonna do it only once anyway.
I publish/update my site about a dozen times on days when I am updating my notes (which I publish to my site). It's a real boon to be able to save the content file, glance to the browser, and see it updated within that time. There is no exaggeration; it's that fast!
It's difficult to take your complaints seriously if you update your site "only once"!
> It's hard to know why would anyone make such weird design choices to solve a problem that has an easy, known solution. Am I trivializing?
It probably depends on how complex you are trying to make things. I'm using Hugo for my blog, and everything I've wanted to do (beyond creating the initial theme) has been a 5 minute task. Now that it includes SASS compilation it's perfect...
I ported my Wordpress blog to Hugo, yes it did take a bit of time for me to learn it. I created my own template, and now its super easy to write a new post.
If your trying to do some form of email list, or e-commerce I would stick with Wordpress
Absolutely agree. I tried Hugo after Jekyll and I run back to Jekyll screaming after touching Hugo. It is an implicit horrific mess with fucked up (il)logic.
Its gets worse if like me you only blog once a year. It takes a while to figure out how to write a post let alone publish it. I can't imagine how long it would take to tweak the template. I too am sticking with Hugo, simple setup. I am not going to maintain a Drupal installation to host my blog. Makes one realise there are pros and cons with each technology.
What do you mean by "It takes a while to figure out how to write a post"? With Hugo it is just adding a .md file inside your content folder, write the blog post and generate the blog with `hugo`. Or am I missing something here? The templating issue aside.
It probably is just me. I find myself having to look up things like configuration for the menu, syntax highlighting. Hugo is a fantastic tool. I should just blog more often.
Biggest problem for me is the template engine and its incoherence, followed by poor documentation.
Also the lack of flexibility in content organization, although this seems like a common feature of static site generators, so I won't hold it (too much) against it.
I started using Hugo thinking I would not need to know Golang, but could use it as a way of learning the language. I'm starting to realize it's probably better to do it the other way around, as without knowing Golang much of Hugo seems unaccessible or very challenging at the least.
This doesn't fit my needs, we are several that interact with the static sites and getting the whole team productive with it is too expensive.
I'm looking into Gutenberg now, at least the template engine looks familiar enough.
> Biggest problem for me is the template engine and its incoherence, followed by poor documentation.
What's wrong with the template engine? Also, before you switch to a different SSG, bring up the pain points in the documentation on the Hugo Discourse forum or as an issue in the HugoDocs GitHub repo. Please.
> Also the lack of flexibility in content organization
An example would help. What part of the content organization is inflexible. Of course there are some rules, else how will the SSG find the content consistently? But an example would help. (Atleast all the files don't have to be prefixed with date stamps.)
> I started using Hugo thinking I would not need to know Golang, but could use it as a way of learning the language. I'm starting to realize it's probably better to do it the other way around, as without knowing Golang much of Hugo seems unaccessible or very challenging at the least.
Examples please. What part is inaccessible? I have been using Hugo for 1+ year, and I am still going string on not learning Go (learning Nim instead, it's awesome!)
> This doesn't fit my needs, we are several that interact with the static sites and getting the whole team productive with it is too expensive.
Typically when deploying SSG for a team, most of the team just contributes to the content (Markdown, for example), and few few folks handle the design of the site layout. So everyone doesnt even need to learn Go templates.
I recommend Lektor [0], because it ships with a administration UI. This means you can give/sell it to people that would otherwise want a wordpress site. Unfortunately that feature doesn't pop out on the staticgen list.
The reason why there are so many static site generators is that they are trivial to write (which is why making your own is a good beginner coding project):
for {post}.md in in blogdir:
if timestamp({post}.html) < timestamp({post}.md):
convert_md_2_html({post}.md)
That's a good explanation for why there are so many SSGs on Github but it doesn't explain why there are so many in use. Surely someone talented would put all the pieces together and outshine all the hobbyist projects but it hasn't happened yet. So either something is in the way or the problem domain is harder than you describe.
In fact, I’m doing that right now! Mostly because I want a blog with a graph structure for linking, and most assume you just want a tree of categories, with tags as a seperate set of trees, usually with a depth of one.
And it mostly just boils down to those 3 lines, with some additional support for the graph structure (and to force the urls to reflect the path taken, symlinks for all possible paths)
Those who are unaware of history is doomed to repeat it, eh.
I use makefiles for a lot of things, they're very straight-forward. If you just follow the UNIX design philosophy, your programs are going to be makefile-useable anyways.
I've tried so many static generators, but they just all fail miserably past a certain point. For a simple blog, just text, etc, they're great. But once you get into adding images, rss, or any sort of complex layout and routing, none of them are really designed to handle that much complexity. Metalsmith came the closest because of it's plugin system, but only because I ended up writing my own plugins and just basically writing a static generator on top of it. But it can't do live previewing at all which is really annoying.
Recently I tried Nuxt because I really like Vue, but although these new types of generators are great for handling layout, and the live reloading rocks, they're not really designed for a truly static site, the pre-rendering includes a lot of unnecessary bloat. There's basically a copy of every post both in the html and the javascript, it's also super hard to control it so it's only the posts for that one page. You can remove the scripts manually but then you lose all js functionality. I gave up trying to find a sane workaround. They're not really meant for content that's truly static that you don't need to update.
I've given up on this point and have just started to write my own, focusing on fast live reloading and easy config (like Vue's cli) because that's one of the other huge problems with all generators.
Have you tried Gatsby? I have tried many SSGs and really like Vue as well, but I tried Nuxt out a while ago and it wasn't flexible enough for my liking. I'm not sure I 100% understand your issue, but I haven't found anything that I can't do in Gatsby so far and I'm blown away by the sources/graphql feature.
No, I don't really like react, and it's probably bound to have the same problem as Nuxt. The issue is that the site, at least with Nuxt, is pre-rendered to HTML, right, but it still needs to have Vue (because usually you would want to then use it to then refresh the content). The thing is this, apart from having to have Vue and a bunch of JS, it also adds your posts inline to the script (because Vue can't just extract the content from the DOM (well, it technically can, but this would be a mess for varying reasons). This is a bunch of bloat since I want the site to be static to be fast. You can delete the script tags after the rendering (using something like cheerio), but this gets rid of all your scripts (which I still need some small ones to for example, lazy load images). I could keep them separate and then insert them back in but then I lose the pleasure of using Vue. It's kind of impossible to solve as far as I see.
Ok I see what you're saying but I don't see why it's a big deal. The JavaScript is non-blocking right? So the static page is still displayed just as quickly. Gatsby does code splitting so the bundles are pretty small and keep in mind it takes advantage of preload/prefetch. Using JS to render a new page is going to be faster than loading the entire static page. Maybe you should try testing out real world performance vs something like Jekyll.
Technically, yes it's non-blocking, that's not the problem. For something like, for example, a store front, I agree, these framework renderers are great because/when:
- You have little data that needs to be pre-loaded (e.g. item name, price, description, thumbnail, etc).
- If you do have a lot of data, then your website is of the type that users revisit a lot (e.g. a documentation site).
- The data is modular (it's not one chunk of data) and can benefit from using a framework to organize it.
- Very little content changes from page to page (in a store front, the majority of the layout is re-used).
- There's a lot of DOM manipulation you want to do (e.g. checkout, cart, etc)
This is not true of content heavy blogs:
- It's a lot of data which must at a minimum be duplicated twice.
- The data is not modular. In one markdown file you have to process the text, images, videos, embeds, etc., all at once. So, for example, you can't take advantage of your framework to generate image tags.
- There's almost zero DOM manipulation needed (at most I might have a portfolio page which needs some js, a lazy-load script, and some share buttons).
- A lot of content changes from page to page (it overshadows any content they might have in common).
- The content is not exactly of the type users would revisit often.
With Nuxt (again don't know with Gatsby, and I think they're working in Nuxt to fix this), you also have to jump through hoops to pre-convert your markdown to html because otherwise you're converting on the client side. Found this out when I looked at the bundles and there were a bunch of emojis in it, turns out it was my markdown converter getting imported into the bundle.
Now, let's suppose this wasn't that difficult, there was some function were you could pre-convert this data and it wasn't including the libraries to do it in the bundle.
Except this is THE pain point of SSGs for blogs. The majority of the problems are here and you would essentially end up writing a static generator inside this function (when I realized this I gave up on Nuxt and similar framework renderers). I would have gained very little for that headache, and how big I would be willing to have the bundle size is a LOT smaller.
And while, yes, bundle sizes are usually small and don't matter for the cases I outlined in the beginning, this is not true, like I said, of a content heavy blog. I don't have a nice a proper benchmark, but I do have some notes from when I tried nuxt. These are the sizes of a single test index page (plain text + a couple lines of css for basic styling) and the full loading times with unthrottled and fully throttled (though this is a bit deceiving* ):
Nuxt w/o Content ~170kb - 250ms - 7.8s
Nuxt w/ 10 Blog Posts ~500kb - 70ms - 14s
Nuxt w/ 10 Blog Posts w/ All Scripts Removed ~110kb - 8ms - 4.3s
You can see how my text is about ~100kb, framework is ~170kb, but the script it produces is 500kb because, I actually forgot, it's reproducing my content 3 times (did not bother to investigate why, just twice is bad enough imo)!
* Now, yes technically the throttled load times don't matter because the static html is loaded (they all paint, even throttled at around the same time), so there's no waiting for the page to load, but who knows what the rest of the background loading does to interactivity (on a proper site, with images, buttons, etc, this was just text) on slow phones with slow internet. Why would I do this to my users? It's not like it's even pre-loading anything useful (this test was with a single page, no other existing pages), imagine if it were.
> Using JS to render a new page is going to be faster than loading the entire static page.
Yes, the lack of a refresh is nice, I'll give you that and it's true that subsequent navigations are faster, but in my case I don't think it's worth the overhead. Plus, so much content changes per page, I could always just fetch the next page and replace the body manually without the overhead of a framework.
Don't get me wrong though, I would probably use a framework based SSG for say, a code blog, where it has more pros than cons. So I can see where most developers are coming from when they use them / design them.
Yea I think Nuxt must have started out with different priorities/tradeoffs than Gatsby did because Gatsby has the idea of sources which gives it a nice structure for specifying what processing/data fetching needs to be done at compile time vs at run time. It's super easy to just add a markdown source plugin (actually markdown support might be built-in) and it will compile it to HTML when your run the build and not on the client. There a ton of source plugins, but if you had to, I think it would be much easier to write one and use the provided abstractions than to write the pre-convert function you are thinking of.
You mentioned TTI (time to interactive) as a concern but that is a metric the Gatsby team seems to really be aware of from the beginning and I think they've done a pretty good job of dealing with it so far, see: https://www.gatsbyjs.org/blog/2017-09-13-why-is-gatsby-so-fa...
In general though I've found client-side hydration to work pretty seamlessly in both React and Vue. I'll be shipping my first (non-trivial) Vue Server-Side Rendered app to production soon.
I think Gatsby would do a pretty good job even for content-heavy sites. It's built to try to only render the critical-path items. If you have a content-heavy site, you most likely have implemented some sort of summary list and pagination and only the first set of links on each static page are going to be prefetched by the browser. So it's not like you have to load all the data up front (and you probably shouldn't for UX reasons), you just have to organize the data appropriately like you would for any other kind of site. I've found that Gatsby's graphql interface makes doing these things a breeze compared to my previous React experience where I've had to mess around with state management libraries like Redux.
I'm confused by what you meant by "you can't take advantage of your framework to generate image tags". Is this in the context of Nuxt processing markdown on the client? Like I mentioned previously, this shouldn't be an issue with Gatsby and there are some cool plugins that, for example, allow you to process images in markdown during the build so that they are lazy loaded and initially show a low-res geometric representation of the image.
I can understand your hesitation to want to work with React though. I was hesitant at first. I would get annoyed at writing JSX, but once I got used to it, I found it tolerable and on rare cases I actually prefer it now.
So you got me to look more into Gatsby because it's good they're interested in performance, and what's interesting is it seems to automate the pre-fetching and lazy-prefetch based on if the link is visible (that I can get more on board with). That's really nice and also overall (especially with the GraphQL querying) it seems to be better suited for blogs than Nuxt so I can see where you're coming from. I wouldn't use it because React, but it does sound nice.
> I'm confused by what you meant by "you can't take advantage of your framework to generate image tags".
I mean that the framework needs to be handed the final html. It has no knowledge about the formatting inside a post. You
have to rely on plugins, often third-party, which don't play well with each other.
I know I've gone on about bundle size (that was just the straw that broke the camel's back) but my main problem is that these frameworks don't help in going from the markdown to the final html which is 90% of the work. I'm not saying they should or can, just they don't, so they don't add enough value imo to be worth the overhead. This is true of all SSGs I've tried though. Yeah they always have a markdown plugin and, for example, that image loading plugin does sound really cool, but can I trust them to work nicely with other plugins? Do the plugins I need even exist? Will they be maintained? I can just feel I will end up fighting them and I've wrestled with too many SSGs already. I'd rather just try to roll my own at this point.
> But once you get into adding images, rss, or any sort of complex layout and routing, none of them are really designed to handle that much complexity.
Could you give examples of these pain points? As a maintainer of one of the SSGs on the list, I'm wanting to better understand users pain points, even if they aren't my users.
Well just off the top of my head, here's what I remember from most to least painful. Some of these are not 100% fixable though or I'm not sure the best way to fix them yet without adding more complexity or some sort of editor to my SSG.
- Layout & Routing - Having "special" pages is usually impossible with "structured" SSGs (like Hugo). For example, say you want a page that's your portfolio and only contains posts with x and y tags and you want it to look different than normal pages. Also see rss below. Or for example archives, where "/year" = "/year/index.html" but also "/year/month/" = "/year/month/index.html" and "/year/month/postname" = "year/month/postname.index.html".
- Sitemaps - I have videos on my blog and usually you want to add those to your sitemap properly. To do this I had to patch together a plugin to fetch the video info from the youtube api.
- Smart tags/embeds - Similarly I had to do something similar to fetch embeds from just the link like "[instagram]link[/instagram]". You have to do this with every provider you want, ugh, awful. Also means fighting the markdown converter you chose sometimes.
- Images - I run a blog with lots of images and different views of those images, so I need to have them all in at least thumbnail size and the regular size, sometimes the original as well, but not always. I used to batch convert new ones by hand but that was a pain. I eventually patched together a metalsmith plugin for this to automate the conversion of originals to "regular" (max post width) and thumbnails but it needs improvement. Edit: And I forgot, actually adding the correct attributes needed for lazy-loading, etc, to the image tags was also a pain.
- RSS, Most do not come equipped to handle rss, and available plugins are too simple (for routing that is, like having an rss feed per tag, per archive page, etc).
- Layout Language - Depends on the SSG, most allow choosing or these days are super flexible (e.g. Nuxt) but those that don't and just use one template language, argh! Template languages like handlebars are just not flexible enough. This was the easiest to fix though. I just use ejs now, basically allows any valid javascript, love it.
I can answer to your comment with respect to Hugo.
> - Layout & Routing - Having "special" pages is usually impossible with "structured" SSGs (like Hugo). For example, say you want a page that's your portfolio and only contains posts with x and y tags and you want it to look different than normal pages.
Have you looked at the "layout" and "type" front-matter?
> Or for example archives, where "/year" = "/year/index.html" but also "/year/month/" = "/year/month/index.html" and "/year/month/postname" = "year/month/postname.index.html".
The "/foo/ = /foo/index.html" or pretty URLs is the default behavior in Hugo, which you can also disable.
Regarding archíves, there are quite a few examples in the Discourse forum. I believe I have seen people implement the yearly/monthly archives using taxonomies.
>- Sitemaps - I have videos on my blog and usually you want to add those to your sitemap properly. To do this I had to patch together a plugin to fetch the video info from the youtube api.
You can have a custom layout for your sitemap. Also, you can fetch data from an API during Hugo builds. Look at the Data feature.
> - Smart tags/embeds - Similarly I had to do something similar to fetch embeds from just the link like "[instagram]link[/instagram]". You have to do this with every provider you want, ugh, awful. Also means fighting the markdown converter you chose sometimes.
Using API like embed.ly and such, and can get such data in real time during the site builds. Alternatively, you can create JSON/TOML/YAML/CSV of all such data, save it to the data/ dirnl before the Hugo builds and use that instead if you want to save on thousands of API calls during each build. This is the same Data feature.
> - Images - I run a blog with lots of images and different views of those images, so I need to have them all in at least thumbnail size and the regular size, sometimes the original as well, but not always. I used to batch convert new ones by hand but that was a pain. I eventually patched together a metalsmith plugin for this to automate the conversion of originals to "regular" (max post width) and thumbnails but it needs improvement. Edit: And I forgot, actually adding the correct attributes needed for lazy-loading, etc, to the image tags was also a pain.
Hugo has inbuilt image processing for a while now. Look at Image Processing in docs. It can do automatic centering, cropping, resolution adjustment, etc during site builds. You can choose to do that afresh during each build, or reuse the altered images from the resources cache.
> - RSS, Most do not come equipped to handle rss, and available plugins are too simple (for routing that is, like having an rss feed per tag, per archive page, etc).
Hugo has this inbuilt. You can choose to have RSS for each "list" page like home page, tag page, category page, etc., and even for each individual post if you like. All of that is configurable.
> - Layout Language - Depends on the SSG, most allow choosing or these days are super flexible (e.g. Nuxt) but those that don't and just use one template language, argh! Template languages like handlebars are just not flexible enough. This was the easiest to fix though. I just use ejs now, basically allows any valid javascript, love it.
Yes, Hugo mainly supports Go Templating. (And I don't have any complaints against that :))
I tried Hugo a long time ago. I believe some of the features you mentioned did not exist at the time. Also if I remember correctly, I did find workarounds for most of what I mentioned with Hugo, but the workarounds felt really messy and inflexible. I didn't mean to imply some things weren't possible, I mostly meant to mention it as an example of a "structured" SSG (by which I mean ones that aren't very flexible with their routes or how content is organized, i.e. they enforce a lot of structure).
Regarding archives, the problem if I remember correctly was getting them to nest properly, not just a "/archive" with all your posts, but lists at "/year/", "/year/month/", etc. until you reached the post. So no path was empty. I don't think I ever got that working.
Regarding embeds, didn't know about embed.ly. Seems great, but it's not free. If there's some free alternative I will definitely use it next time around. One of the main reasons I use an SSG is to keep my costs close to 0.
> Yes, Hugo mainly supports Go Templating. (And I don't have any complaints against that :))
Maybe I'm weird, but I can't stand 99% of template languages. They're too watered down. I want the full power of a programming language, or alternatively, some easy way to manipulate the data the template gets. Correct me if I'm wrong, but I don't remember Hugo having the latter either.
> I mostly meant to mention it as an example of a "structured" SSG (by which I mean ones that aren't very flexible with their routes or how content is organized, i.e. they enforce a lot of structure).
I still don't understand this point. You are free to put all your files in a flat structure like:
content/
post1.md
post2.md
But if you want structure on your site, just set a structure in the content/ dir, and that will be mirrored on your site:
content/
posts/
post1.md
post2.md
about.md
> Regarding archives, the problem if I remember correctly was getting them to nest properly, not just a "/archive" with all your posts, but lists at "/year/", "/year/month/", etc. until you reached the post. So no path was empty. I don't think I ever got that working.
You will find many themes, at least right now, that implement "bread crumbs". Even searching bread crumbs in the Discourse forum will yield a lot of results.
> Regarding embeds, didn't know about embed.ly. Seems great, but it's not free. If there's some free alternative I will definitely use it next time around. One of the main reasons I use an SSG is to keep my costs close to 0.
I just arbitrarily threw that name out there. While I am not aware of 100% free API services, there are a few I know of that provide that service for free with rate limits.
> Maybe I'm weird, but I can't stand 99% of template languages. They're too watered down. I want the full power of a programming language, or alternatively, some easy way to manipulate the data the template gets. Correct me if I'm wrong, but I don't remember Hugo having the latter either.
What kind or degree of manipulation are you looking for. The replaceRE template is pretty powerful for my purposes.. I use it to insert anchor links next to headings as I don't like using JS solutions to do that.
My problem is the mirroring itself. I don't want, taking your example, /posts/post1 just because post1 is under posts. You can get around this with some SSGs but this doesn't change the fact that they're path oriented. For example, I think it was possible to turn this off in Hugo, but then you had to do some workarounds for specifying templates because normally the templates have to be aligned with the paths. Plus it has a bunch of weird separated page "types" (archetypes, taxonomies, etc)
For comparison I now use my own metalsmith plugin which is the opposite of these types of SSGs. It only relies on the post metadata. I can basically say, pick all posts that match x criteria, use x route (it can dynamically generate them based on metadata variables), use x template for this route, and set basic settings (posts per page, etc). All from one place. Files can be organized however I think makes sense. There aren't different types of pages or anything. The only "special" thing I had to do was for /year/month/date/ archives, but I plan to remove that exception with the SSG I'm writing now.
Regarding the archives, bread crumbs are not what I mean exactly. I want the pages to also be paginated. So /year/ is not just a list of links to all posts or links to all months, it should paginate the posts list for that year as well if they pass the posts per page limit. Seems like this has never been implemented, see this four year old issue I found: https://github.com/gohugoio/hugo/issues/448
> What kind or degree of manipulation are you looking for.
I often want array manipulations. For example, to create tag clouds. I'm sure it's possible, but I doubt it's pretty. With something like EJS, I can just have the logic in plain javascript, right above the div that iterates through it. I will grant you, I'm not sure this is the best solution. With the SSG I'm writing, I've been playing around with the idea of having a header or footer section in javascript for the templates, where you can run this type of logic and the variables will be available in the template. Kind of how when you use a JS frameworks (e.g. Vue which I love) if you have something complicated to iterate over, you remove the logic from the template. This would make simple templating languages attractive again.
> none of them are really designed to handle that much complexity
Be careful what you wish for! I had used Nikola, but every release kept handling more complexity. Which meant an ever increasing number of options, but most annoyingly a large number of warnings due to config options that had changed, been obsoleted, interacted differently etc. Nikola is one of those tools that generates an initial config file for you, which exacerbates the problem since you probably don't use all the config items, and then have this option warning mess due to those items.
Yes you can install a version pinned version of the tool, but then have to do the same with all the dependencies. Before you know it, Wordpress seems easy and trivial.
Never tried Nikola, but I'm painfully aware of the problem. I think I've tried and migrated through enough SSGs at this point though that I think I can write something better.
The main problem IS the config imo. That and plugins (and their configs). Don't know if you've tried Vue's new CLI, but my idea is if I don't want to or can't abstract away the complexity without imposing limits on flexibility, the next best thing is to "visually" abstract it by making the configuration happen in a UI like Vue's CLI. This will get rid of errors because you would be able to stop the user choosing conflicting actions, and things that cannot be abstracted in a config, usually CAN be in a UI. Main one, for example, and the one I'm focusing on is routing. There's tons there that can be abstracted in a UI there. You can also add hints, links, etc in a UI. There would be no need to be looking at the docs all the time. In the future hopefully I can expand the idea further to include an editor, but I have to keep my goals reasonable or I will never finish.
As for how many features and how complex, after migrating my site so many times I feel the following should be included (because if they're third party plugins they end up un-maintained): RSS, Sitemaps, Image Resizing, and maybe Embeds
PS: I tried wordpress with a static generator plugin once, it was horrifying, never going back. Even ignoring the static generator plugin, it still did barely better than the previous SSG I'd been using. The plugins were all of wildly varying quality. In particular I was constantly fighting the one that resized my images.
That's why I've started a web framework with the goal of being entirely flexible. I've made all code ejectable, minimized/simplified the glue code (so that you eject beautiful code) and made the stack flexible (you can remove/add a frontend/backend/ORM/database to your app easily and at any time). That should give you the flexibility you are looking for.
This looks interesting for making SPAs and more app-like things, but then I haven't found things like Nuxt to be inflexible for that (never actually created a SPA with it though, just attempted to use it as an SSG).
Doesn't look like it would work for me though for the same reasons Nuxt doesn't. It's not really lock-in pain that's my problem btw, but more config fatigue and missing features, and if the SSG has a plugin system to counteract this, then there's the problem that most don't work well or age quickly (imo this is usually because the plugin system is not strict enough), and regardless of whether they work, you end up with this patchwork of plugins, with a bunch of hacks and glue code to make them interact nicely, it's awful.
For me, lack of nice (ie. controllable, but 'automagic') image handling is a huge bug bear in nearly every cms out there, static or otherwise. Perhaps I didn't find the right platform/plugin...
In my case, I wanted to have 1 source image that was resized at various (author controllable) sizes and then saved them, while also generating supporting HTML (eg. 'srcset' to automatically swap between them). I ended up with a couple of ways to template it in [0]:
I think this is a task that is handled by an optional CMS, not the static site generator itself, though I agree it would be handy to have a little helper snippet to do that during build.
There are CMS solutions for static sites which will probably handle images, and all kinds of content, easily. Check out Dato[1], Siteleaf[2] or Netlify CMS[3].
Alternatively you can use external tools to prepare your images and simply rely on the standard HTML srcset within your static site generator of choice. I use RetroBatch[4] to prepare my images.
Exactly what cmroanirgo describes, also see my reply to epage (https://news.ycombinator.com/item?id=17961353) for that and my problems with rss, and some other things I didn't mention. For images, I ended up writing my own metalsmith plugin to resize images to different sizes and add all the attributes to the tags properly.
You want to write a simple static website. Now you have to choose between 100 generators. Your life has become a little bit worse.
Personally I rolled my own, but I can't say I would necessarily recommend it. But in less than 300 lines of JS it can generate by site from Markdown, with index pages and RSS, as well as watch in the background for changed files and update them live. It was a fun and useful learning experience though.
I have really, really enjoyed building my personal site (https://hotair.tech) in Gatsbyjs. I am not sure of how steep the learning curve is as I started using it w/ the intent to learn React and GraphQL. It strikes a good balance of being both a productive framework and letting you use the full features of GraphQL and React.
I much prefer it over my previous experience w/ Jekyll.
I love Pelican. It was relatively easy for me to migrate from Octopress (which seems pretty much dead at this point). With pelican it was pretty easy for me to write by own extremely lightweight theme: https://brashear.me/blog/2017/07/30/migration-from-octopress...
My Python is only marginally better than my Ruby (not great). Even so, developing my own theme was easy following their docs.
Looking at their blog[1] they seem to do releases very infrequently. 3.5 was released 2014-11-20. 3.6 was released 2015-06-15. 3.7 was released 2016-12-12. It seems like each release is about a year and a half apart. By that cycle we're about due for one.
Well, I'm still using an ancient version (2.8?) cause the last stable broke the Markdown footnotes' linking (maybe it's a bug in my theme).
I'll probably look this week if the bug was fixed, but I'm not in a hurry, last time I updated I didn't realized they eliminated some Jinja2 corner cases that I abused for scoping variables outside code blocs and I think I'm still using the global context in a "creative" way... ^__^;
Possibly because stability is a good thing in software. Not saying that's the case with Pelican, but I like things that don't change much. It often means developers know what they're doing.
Pelican is great, especially if you spend a little time configuring the URL structure to remove the `.html` from the end of the URLs. I think something like this will work for most pages (might be incomplete):
My understanding of the AGPL in this case is that if you publish a blog with Pelican, you have to also publish any trivial fork of Pelican that you create, even if only by a single trivial patch.
Seems rather onerous given how likely us devs are to tweak something here or there.
I'd gravitate towards any of the many MIT-licensed generators instead.
Dead simple. I set it up six years ago, with maybe a full day of work. Never really had to do anything since then, except write my entries in markdown file, and run a script that generates the website and uploads to my nearlyfreespeech hosting server.
The only thing I don't like about SSGs is the need to be on a computer that have the right software installed: I use different computers and sometimes I just want to add some link into my website. This leads to too much work for just a link.
I've been interested in [1], that is written in Rust and is available in a single binary. This eases the installation process.
Something interesting to consider are client-side site generators. I don't think there's a lot of them, but if you want to write your articles on markdown files on github/vim and update your website with a git push, it's a nice thing to consider. I wrote my own tiny one because it's fun (and it works just right for me), but see [2] and [3] if you're interested in these type of solutions. They work well with Github Pages.
Well, you can add Netlify CMS to your statically generated web site. That adds a configurable admin web interface through which you can add or edit your pages without installing the generator on the computer you are currently using.
As a few others have mentioned, I highly recommend writing your own static site generator, unless you know the specific reasons you need something more advanced. It's a fun exercise and was a great learning process for me.
Here's my personal hacky take[0]
You can get pretty far by simply supporting Mustache templates[1], Markdown parsing (even that isn't necessary, though I did it since my old posts were already in Markdown), and a metadata format (ie frontmatter, or something similar. I went with toml files sitting next to my content).
I'd love to see a graph of the stars over time. Or perhaps a graph of a new-stars-per-month statistic. That would show which ones are getting more popular and which are in decline.
Jekyll has a ton of stars, but that's probably because it's been around so long.
We used to have those charts per site generator on the detail page before the Middleman -> React Static rewrite of the site.
Would love to see them back myself. Pull Request at https://github.com/netlify/staticgen would be super appreciated, since it might take a while before any of the main contributors will have time to add it back in.
I tried Hugo, Jekyll and Gatsby. Assuming that a static site is 95% likely a marketing (self, company or otherwise) site and a marketing site needs to impress, a static site generator should be first and foremost built from the requirements of frontend and not leave the user to "theme" some default HTML.
Gatsby is ridiculously fast (React based) and its plugin universe is full of all the common features you could ever need. It has built in 1-click service workers plugin for offline access, 1-click plugins for prefetching links you put on your page, auto-inlined-css (in v2), all kinds of markdown + fringe requirements like LaTex, video embedding, things like Call to Action plugins, MailChimp sign-up-here plugins etc. To get a feeling of the snappiness, check out their landing at https://www.gatsbyjs.org/ and their plugins here: https://www.gatsbyjs.org/plugins/ .
The community pushes and PRs at break neck speed every day and is super friendly - can definitely get the support you need. Lastly, it is a great way to "inverse learn React" if the objection is "Wow, I don't know enough React". React by itself is not that opinionated and Gatsby has enough good practices of putting together a React framework for you to use productively.
Just wanted to point out that there are at least two kinds of fast: fast to build and fast to load. And while Gatsby-based sites are indeed very fast to load (although I haven't compared a Gatsby site with an optimized Hugo site), they are painfully slow to build.
But it is truly a pleasure to work with; that's for sure!
In develop mode, hot module reload (HMR) changes the text immediately on the screen as you edit. But yes, HMR and caching has some glitching once in a while.
How do you people regard the kilobytes of JS (50—100KB in the very least) that a Gatsby-built website will inevitably require? Big deal? Not a big deal?
I'm surprised nobody mentioned this but this website and the whole JAMstack thingy is basically a PR stunt from Netlify.
Static sites generators and the JAMstack are inherently crippled.
With a JAMstack, by design, everything needs to be rendered on the client. This means poor performance on mobile, loss of control over SEO, and virtually no SMO for dynamic content.
Kinda funny to promote a crippled stack that hard...
Shameless plug: If you want to organize your content with files and directories without any configuration files and all that fuzz, I created PLY[1] this summer.
All it does is convert .md files to .html and optionally uses nested Golang templates. There are some tricks behind the scenes, like support for tags and meta data (just like regular static site generators). Flexibility is concentrated into the templates, so no other files are needed.
I think the content (files) should reflect the structure of the webpage as close as possible when using a static site generator. When reducing complexity, we can go all the way down to the filesystem, where files and directories are the main building blocks. Content and design must be separated as much as possible.
I have not tested all static site generators out there, but the few that I tried did not satisfy my demands. So I just made my own (for fun and learning).
Jekyll has been working well for me. I have around 190 public posts, dozens of pages and 50+ drafts on my site.
With Jekyll-Assets I work with SCSS and everything becomes minified, along with getting md5 tagged file names for cache busting with no effort to set up.
When writing a blog post it takes around 2 seconds for live reload to kick in and refresh the post (which works nicely as a near real-time preview when writing). A full site build takes around 10 seconds but I only do this when deploying so it doesn't matter that it takes so long.
The only thing that sucks is for whatever reason I cannot get Jekyll to work at all with Docker for Windows which ultimately may end up convincing me to move to a different generator in the next iteration of my site. The devs don't seem to want to address the issue.
I gave up on these a while ago when I realized a very small amount of scripting (<100 lines) and pandoc gave me everything I wanted to maintain my site.
Being able to easily create and pack themes is meta-important. That is, a good set of themes cannot appear by a community effort unless creation of a theme is reasonably easy and well-documented, and themes are self-contained and easy to share.
And I'm quite the opposite. If your SSG comes with prebuilt themes and a ton of deep integration overhead (like Hugo) I'm going to pass. Just give me RSS, blogging, ability to use any templating language, and I'm good to go.
Sure, having good existing themes is important, but it's much harder to quantify.
Also, themes are not 'one size fits all', so consider meeting your local designer/frontend developer (or contact me :) to create a theme or at least adjust an existing one. It makes quite a difference when the theme fits to your needs.
Can someone suggest a good static site generator that uses Org files?
I'm looking for something I can have a blog & wiki with that integrates with how I already take notes. Gollum & derivatives seem alright but very bare bones.
I have developed an Emacs/Org Mode package that can export subtrees or whole files to Markdown files. The front-matter stuff like title, author, tags, categories, dates gets auto-derived. These Markdown files are Hugo compatible.
I don't see it on this list but I think the Hacker News crowd may be the R blogdown package. (Different than the JavaScript blogdown on the top list; ) The main features for me are good LaTeX support (for formatting mathematical expressions) and R and Python code blocks for creating charts, etc. It's great for a moderately technical blog that has equations, data visualizations, formatted code blocks sprinkled throughout the text.
Does pmWiki count? Files are stored as plain text, though it does go through the php on rendering?
A few months ago I saw a recommendation n LinkedIn to use it for a personal-wiki, just storing notes and remembering things. I have found it to be really fast (1G DO node) and super easy to get going and keep doing including from multiple devices - as long as they've got a web browser they're good to go.
I look at static site generators every now and again, and I'm totally overwhelmed at the range. Beyond starting with trying out the popular ones, is there a way to get into this whole thing without losing my way in the rabbit hole?
I say this coming from a traditional PHP + MySQL CMS background of 15 years, the irony of the vast array of PHP + MySQL CMSes is not lost on me.
Ultimately, they all do roughly the same thing in the same way. They're just Markdown-to-HTML converters, with some nice quality-of-life features tacked on.
Just pick one (even just one at random will do), and start there. It's easy enough to change your mind later.
There needs to be a term for "static DOM site generator" or "non-scripting site generator". (At first blush, I would have called this "static site generator", but now I know better.)
I.e. something that performs well on all devices, and is optimized to just providing static data via CSS-styled HTML.
Does anyone know of a recognized term for this thing?
That's generated using Jekyll, and executes exactly zero lines of JavaScript. I think most static site generators, except maybe Gatsby, can do that. Just don't put any script tags in your template.
I kind of cheated at making a 'static site' though as I'm using PHP for some dynamic stuff like my contact form and latest Instagram posts (but that's via AJAX)
I used Jekyll until the combination of various Ruby versions, FreeBSD pkg, gems, and unaccountable bloat drove me mad with rage.
Have you ever looked at the dependencies for Jekyll? Why does it need a JS compiler? I mean, how many lines of code and how many Ruby packages with very specific version numbers does it take to convert markdown to html?
I'm now using Pelican and it hasn't driven me into a rage yet. Happy that development on it is slower and seemingly more deliberate. Then again I haven't had to upgrade it yet.
Does anyone have a good theory about why (1) there are so many static site generators and (2) market share is so widely distributed? Is this a case where (1) it's easy to build static generators and (2) everyone's needs are a little bit different... or are there other dynamics at play?
Also, static generators and bundlers (webpack, parcel, etc.) strike me as needing to solve many related problems. Do we believe there's a meaningful integration to be reached down the road?
I've hardly blogged in the last several years, but I've tried out half a dozen static site generators (SSGs). I think it could be a nice way to introduce/familiarize yourself with a programming language, beyond just the toy exercises. Once you understand one SSG, they're all very similar in essence, so it becomes a good way of getting up to speed with language features and idioms -- at least in theory.
I'm currently playing around with Frog (Racket based SSG).
I found Hugo to be a convoluted mess. Pelican on another hand was very easy to get started with. Plus it's written in Python so debugging it is easier.
I did a crazy thing and used sapper[0] for a recent static site. It has a beta feature that allows for exporting a static page, and it worked really well for me. Fast, modular, es6 and little setup. Would definitely use it again.
I like the mindshare of the Jigsaw generator with Laravel, it uses the Mix bundler and Blade templating, basically Laravel without the backend stuff. It might be a good choice for people who want to start with a landing page before going full saas. Strange that it's not more popular..
Is there a SSG plugin built on top of rich text editors like docs to just publish/deploy static web pages?. I remember buildin static website's for non tech friends and maintenance/keep up over time is always painful for them.
So what would be the recommendation for something that generates static blog-like pages? Assume I know nothing, or maybe python and a liiiittle bit of jinja.
Your requirements made me think of Cactus (https://github.com/eudicots/Cactus). It was pretty nice but I don't think it's being actively maintained anymore.
Why not try http://ngDocumentor.github.io ? It needs no generator. Works as a SPA. Works as a Offline app (PWA). Custom routing feature, simpler search. More just one json config file to set up the whole site. Serves markdown files on the fly. Try it you will love it. Works on Github/Gitlab pages as well. No root access required.
The speed of generation doesn't seem much of an added advantage since you're gonna do it only once anyway. It's hard to know why would anyone make such weird design choices to solve a problem that has an easy, known solution. Am I trivializing? Maybe, but I know how much time I spend on rendering when I am working with Flask + Jinja and how it's 10x worse with Hugo.
Sadly, moving my blog way from Hugo would be too much work and I have to bear with it.