So for those case, the solution is to use a CMS like Wordpress. Which I don’t want.
There are already a few CMSs for static sites, much like the solution you've made. The old-school one is Movable Type, but nowadays there's also one by Netlify, Publii, Siteleaf and a few others. There are also plugins for Wordpress that generate static sites from it (meaning you don't have to expose WP itself to the outside world).
That said, making your own solution can be the best option.
I use Gatsby and then teach clients how to write markdown. Then they edit markdown content in gitlab, once they save (commit), the CI/CD regenerates the website and deploys to S3/Cloudfront.
There are other solutions, such as using wordpress or contentful to provide content and then regenerate the website when something changes. I think the creator of Gatsby is creating something like that as a business.
The article in the top of this thread is interesting. I can just add that in Hugo we have tried to make it simple for the simple stuff, but also make the "harder stuff" possible. We have naming conventions for layout files to keep it DRY (to avoid having to set "layout: blog" or something in every content file (you can)) and we have some special meaning behind "index.md" and "_index.md" -- which among other things allows for a navigable and not so rigid content tree. We even have plans to, in near future, to extend that tree into the content files themselves (ToC, paragraphs, sections). We may have different trade-offs than the article writer: With many sections and thousands of files in a deeply nested content tree, Hugo's layout system its speed may make more sense. Or not. So we do try, but it is hard to make everyone happy. I'm bep on GitHub.
Jekyll has most of what you're looking for as a plug in: jekyll-admin.
It doesn't handle authentication, so you'll need to put /admin under authentication on the web server level, but it allows you to edit and write pages, save them to drafts, view them as drafts, publish them, modify their metadata...
The only downside is image hosting, where the friction is still a bit too high.
I do like the idea to have a statically generated site and have all the content in plain text managed via git. Unfortunately it is ideal for text oriented content only. Once there is a lot of images in your content it becomes a pain to manage it in a convenient way.
I tried pelican, but failed as didn't find an acceptable way to write a content. I have a kind of blog with around 30 to 50 photos per post and there is no way to put into the text as convenient as in wysiwyg where it is possible to select the picture I need.
Thus I decided to abandon the idea to migrate to SSG. Even though I tried it and dreamed about it a lot :)
Yep. I'm hopeful that someone will inevitably turn up in the comments and reveal a great way to do it but everything I've seem is just janky and awkward.
I've basically stopped using my static site as a result of media management being a pain. I'm probably going to do back to Wordpress or something (shock horror!). Wordpress isn't hard to manage at all quite frankly, it's just a different set of compromises compared to a static site. It's also super easy to manage rich media and as I'm falling squarely on the side of 'get shit done' it's looking like a good option.
It's trivial to cache it well and update it. Yeah it's not as secure but there's a risk vs usability judgement that has to be made. And I think I'd prefer to be producing content and having some good backups rather than just not use my site.
Check out HardyPress. They host WordPress in an anonymous environment that goes to “sleep” when you're not using it. A static version of the site is deployed to a CDN when you're ready to publish changes. It's been the best of both worlds for us.
If you’re not against PHP and hosting PHP code, as mentioned in the OP my go-to tool would be Kirby. The mix of static content and a powerful content API is the sweet spot for me, when I don’t absolutely need static HTML. It does require a paid licence though (note: I’m not affiliated with Kirby or its developers).
I'm just looking through now. It does look pretty good. I'll have to play with it and see if it falls in the right spot between 'I'm too lazy, just point and click' and wanting something lighter-weight and easier to reason about.
Forestry.io is a CMS for static sites that includes a media management interface you might like.
We also support uploading images to Cloudinary instead of committing them to your git repo to prevent repo bloat.
Depending on what you're trying to do, a non-CMS option that will remove some of the tedium of inserting all these images is to take advantage of Hugo's Page Bundles feature. With this you could just group a bunch of images in a folder and iterate over them in your templates.
> I sometimes talk with developers who praise static site generators as simple, which is hogwash. I’ve seen a few projects where content editors were handed off a site based on a SSG (especially in startups where devs may dominate the conversation), and could not manage any change without a lot of training and assistance. Nothing simple about that. What those developers probably mean is that they find static site generators elegant.
It sounds like this article is using "simple" to mean "easy", and "elegant" to mean "simple".
An SSG is simple, and it's easy for people who know "the command line, the plain-files-and-scripts philosophy, git and ssh" (which is not quite the same as "developers", though there's usually a large overlap).
As much as I like Hugo, I recently stumbled upon the terrible Go templates! This is probably the strangest and most limited template engine I'm aware of. It might be nice in an application to actually limit what can be done in templates, but in a tool like Hugo where the user can not easily extend the core functionality, more powerful templates would be necessary. I hope Hugo switches to a more powerful template engine one day.
Besides that I agree with the assessment that these tools are from developers for developers. In the end a static site generator is more like a special kind of build tool and less like a CMS (what non-technical users would need).
I've been building websites since the mid 1990s (including everything from small personal sites to large content-managed sites for the BBC), and I now run an agency that builds WordPress sites for large non-profit clients. I've been looking at SSGs myself recently, and much as I like the idea of static sites I've come to very similar conclusions to the author. There are two observations I have about this from my perspective:
1. People often forget that "making your own" also entails a huge risk for a client. What happens if you go bust? We're constantly being contacted by organisations who were talked into a proprietary CMS and then left in the lurch when either their relationship with the agency broke down (which often happens in this situation because the agency know the client is locked into their CMS) or a company's lone developer left.
2. No content editor should have to use anything much beyond a Word-like interface, even if there are separate TinyMCE fields for separate areas in a page template. Even Markdown, which seems elegant and simple to developers, can cause all sorts of issues with non-technical content editors - and most clients outside the development bubble are non-technical. I feel like the lessons learned at the beginning of CMSes - for example, you shouldn't expect anything but pain from expecting clients to edit HTML - haven't been fully understood.
The one end-user benefit from SSGs seems to be that the site is packaged as static files and is therefore faster and easier to deploy, but is that really worth jumping through all these hoops? If any of these SSGs wants to reach a broader market, they'll need to have a WordPress-like interface that then publishes the static files and somehow manages to cope with dynamic things like search and filtering in an accessible way.
One service I've been interested by is https://www.hardypress.com/ (just tried it out, not affiliated in any way) which effectively takes a WordPress site and publishes a static version. They cope with form submissions in a similar way to Netlify (I think) and also deal relatively with querystrings that trigger a filtered listing. I think this is the only direction I'd be comfortable with for my clients because it gives them all the benefits of a user-focused CMS with a static site generator, while allowing them to take the site to one of the many other WP agencies if they choose to.
Gotcha. IIRC search is taken care of by their rewriting of querystrings. Comments and things like WooCommerce aren't going to work, but if you want to do that kind of stuff SSGs aren't going to cut it - to do any kind of per-user processing you need some kind of system to do that processing, which SSGs aren't going to provide. We're thinking about using HardyPress for some of our non-profit clients because we can probably work with something like fixed donation amount buttons and Stripe.js.
Yes, Lektor is great. The outstanding features are the admin interface which allows even non-technical people to create and edit content, and the content models which allow to work nicely with structured data.
For example, in the past I have built a multilingual media database with Lektor, where items could be, say, books or movies, and depending on the content type I could enter a "number of pages" (int) or "duration" (time) or "author" (selection from a list of "person"-typed contents), and the admin interface would be auto-generated. I haven't seen a similar functionality in other SSGs.
Downside: For large sites rebuilding takes very, very long...
I think static site generators need a more rigid content API. Problems start when these tools try to pack too many features trying to make everyone happy. They become small CMS and as the author mentions introduce poorly documented hard to grasp features.
Rolling your own specific static generator is quite easy, the bulk of the work being gluing libraries together. What is worse, using an existing tool in a way it is not meant to be used or maintaining your own?
I felt the same when looking for a generator that could be learned in one afternoon and which would allow me to easily change templates/themes whenever I felt like it, months later. The solution was to rely exclusively on pandoc for markdown to HTML conversion, generating some .md files when necessary (such as from a bibliography, or if so I wanted from a blog/ directory). All without any real templating and relying only upon my bare CSS knowledge -- a nice side effect was forcing me to adopt a minimalist approach.
Have you looked at gatsby? It doesn‘t fullfill all points but it comes closer than any other SSG. I think it fully satisfies 3, 4, 5 and 6.
The content API that is not limited to filesystem data puts it in a different category than other SSGs for me. They also seem to have the ambition to take on wordpress. It can involve some configuration though. It doesn‘t make the use case in the article trivially easy either.
You are grossly simplifying the value that SSGs provide and problems they solve. Gatsby has some quirks, but it does strike a good balance of providing value whilst giving you plenty of control. It does the data capture and transformation of content I want, it gives me a place to explore and visualize those parsed datas, and it lets me control how to render that content in a context that very closely resembles the final artifact (jsx, html). It doesn't cram a new DSL down your throat (jsx is close to html enough, and, it's optional). It has excellent debugging in node and the browser. Hugo doesn't have those, Jekyll super doesn't have those, and everyone's home grown scripts certainly don't have all of those. There isn't a one-size-fits-all, but saying it's a poor tool because it has a lot of dependencies is silly and immaterial.
The bottom line is flexibility and speed. With Gatsby you get both. Only looking at it as a .txt > .html convertor is very limiting. I generate 1,500 webpages every day from custom datasources with Gatsby. Using React components gives me DRY code. This gives me very great flexibility during development and great SEO and speed in production.
Give me a tree navigation. Oh, it's not supported? Now, in order to implement it, I have to figure nodes/graphql/webpack/fragments (I know the tech, but it it's _used_) to get a solution that I could whip up myself in 30 minutes if the tooling and techstach wasn't bogging me down.
There is a hidden cost to large peices of software with high ceremony. Most people ignore it because of the initial speed you get in setting up the project, but fail to realize the downstream time that will be wasted dancing with these large hammers.
This matches my impression of Gatsby after a day with it. I bailed a bit more quickly than with Hugo, so I refrained from adding a Gatsby section to my already too long article. Also my main takeaway was “Gatsby is an overengineered mess from (and favored by) people who are already all-in on React and GraphQL and don’t realize the learning curve they’re asking others to climb to build simple sites”. Too categorical for something I’ve only spent a short day with, so I decided not to include it.
While I do know React well enough, when trying to work with local content I had to follow a tutorial that asked me:
1. To install 2 plugins
2. To copy-paste 3 different chunks of boilerplate code (configuration, the code that maps filesystem data into some kind of representation — maybe using GraphQL already, I’m not sure — and lastly the GraphQL queries to retrieve that data).
3. To personalize this boilerplate code, which requires me to learn GraphQL.
It could be that all this overhead is worthwhile because it enables you to do complex things. But from what I’ve read I wasn’t even sure that Gatsby could achieve my use case without me duplicating my information architecture as “feed content to the in-program representation” code, and I didn’t want to risk spending a second day only to find out that it couldn’t. (Your comments about tree navigation, as well as some of the GitHub issues I’ve read, suggest I was right to bail out.)
My actual takeaway is that Gatsby might be a good fit if you already know React and GraphQL (or already wanted to spend time learning those), and are working with remote content from a headless CMS and some other sources. But for local content only, unless you already know Gatsby or want to use that project to learn it, it’s needlessly complex and overkill.
I think you might be right on with "people who are already all-in on React and GraphQL". I honestly prefer writing JSX/React+GraphQL to a template language even for static content. I like that gatsby makes that an option without making an annoying SPA content site. It‘s a good reality check that this is likely a niche prefer ce.
And I also want to use headless CMSs or other data sources, in my current project a GraphQL source, which maps right in with the (very recent) schema stitching. So I think gatsby is the right choice for me, but I will carefully consider recommending it in the future. Being a VC backed company they may have more cheerleading than other open source SSGs going on.
The amount of (dev) dependencies doesn’t matter that much to me, but I agree about the client side. I wish gatsby could emit a version without client side routing / react. I also find the way to create and manage pages (and yeah trees) is not as flexible as it should be.
"Just a txt > html converter" is what every developer builds for themselves at some point and hence the 300 different projects that already do that. I‘m glad someone is making a database backed (kind of) static site generator for once, even if it brings some code weight with it.
> The amount of (dev) dependencies doesn’t matter that much to me, but I agree about the client side.
I read a blog post recently that really resonated with me .
> And dependencies? People easily add overengineered “full package solutions” to solve the simplest problems without considering their costs. And those dependencies bring other dependencies. You end up with a tree that is something in between of horror story (OMG so big and full of conflicts) and comedy (there’s no reason we include these, yet here they are):
But yeah, I don't mind where the data is stored. It's the html generation that people go overkill with.
I’ve been baffled by how brittle static site generator tools are, and how forcefully they push their workflow/concepts onto the user.
I gave up on Jekyll when I tried to hook it up to hit & push each published site as a branch patented to the site branch & the corresponding master commit that was used to generate it.
I ended up fiddling with my SSG and exploring software designs that make it easy to add in weird extra behaviour. I really like how Dist::Zilla (Perl package publishing tool) allows so much flexibility and reuse, without many strong opinions of its own (mostly that packages are a collection of files and that prepare plugins should run before publish ones).
> This is a simple tool/library. There are no opinions or abstractions, aside from the abstraction needed to host and export content. There is nothing preventing you, the developer, from doing what you want with your project. Parse and render markdown files in a directory for a blog? Build a user manual? What ever you want, you can do.
> I tried using Gatsby for a project of mine. The moment I tried to do anything not supported OOTB, it seemed I was fighting the tooling (and webpack) at every corner. It was incredibly difficult just to get a simple tree navigation.
> One thing I thankful for though is that it gave me a new-found love for the simple and non-flashy libs/tooling.
> In the end, I wound up writing my own static site generator.
> You may say to yourself "So you just wrote your own Gatsby!?"
> No, I didn't. I wrote a thin lib that you can register endpoints and extract them to disk. It does absolutely nothing else. The idea is that I will wrote my own markdown rendering, navigation, html/css, etc for each project. "But what about the time it takes to implement all the features you need!" The time it takes to implement these minor things take far less time in the long run, and I will never have to be in an endless fight with the tooling to get simple tree navigation. Every feature I implement is exactly what I need, no more, no less.
> Sure, it isn't as cool as React, webpack, etc. But I'm a lot happier.
I agree with the author that SSGs are tools written by developers for their own use. But what's great about the file-based, command-line-driven interface is that it's possible to hook the input side up to some more machinery if you want a GUI CMS.
I work for Forestry.io, and our product is a CMS that aims to ease the pain of non-developers managing content for static sites. We are committed to bridging the gap between copywriters and developers. I am a big believer in the potential for static sites to transform the web, but I realize there is a lot of ground left to cover.
To address OP's point about the need to have a bit more control and freedom in the complexity of the content (instead of having only markdown etc), Next.js offers an "export" script that will export the app as a static asset.
I made a static website with it recently and found it very quick to use, assuming you know React.
No config or setup required (something rare on js projects nowadays), really just "npm install react react-dom next" and you are good to go.
Build a react component at "pages/about.js" and boom, yoursite.com/about routes to this component.
• it is template-driven, via Go templates engine (the theme/wiki.tpl is the entry point, all other templates are loaded dynamically) — no need to put files in special place in hierarchy (unless you impose it on yourself);
• it has `glob` function for matching files by pattern, e.g. `glob "/20??-??-??-*.md"`, and can render the contents of files loaded this way;
• it has `matchre` function which allows simple editing of page contents (you should be able to cut contents before/after a `<!--more-->`, etc.); by the way, I kinda feel, that the three points above, taken together, probably already make it Turing-complete in some unholy, non-euclidean, blasphemous way, akin to C++ templates...
• the "only" caveat being... it's not actually a SSG (yet™). It's more of a "personal wiki/notetaking" app currently. But the next step and goal in its development is to convert it to a SSG, only I'm still pondering various approaches to go there. And... it's kinda on hiatus now, in that I'm not developing it recently. But if I will develop it, it'd be exactly to convert it to a SSG now, so you should be fairly safe to "watch" it on GitHub. If anything shows up in your inbox, most probably it'd be a set of commits converting it to a SSG. And this very thread on HN may, or may not, make me get back to work on that ;)
> Originating in simple blog engines, static site generators treat pages as a single content chunk (often in Markdown) with some metadata sprinkled on top. If you need several long chunks of content (say, a product short description, long description, technical specs, and a list of vendors), you’re out of luck.
I've struggled with this too. I'd really like to write in unadorned Markdown, because I'm using Trello as a headless CMS, but I also want the Markdown to map to an object containing discrete chunks of content.
The solution I settled on is to map level 1 headings to separate properties. The content that follows each level 1 heading is converted to HTML and becomes the value of the corresponding property - unless the content is a code block, in which case the code block is parsed as YAML to get a nested object instead of HTML.
I'm one of the Co-founders. We built TakeShape to be a more end to end static site CMS. TakeShape has a GraphQL API and Static Site generator that uses nunjucks for templating. You could also just as easily only use the GraphQL API with React or GatsbyJS's new native 3rd party API support.
TakeShape has built-in integration with s3, GCS, FTP and Netlify.
TakeShape comes after 7 years of running a design agency and trying to balance the best of many different styles of CMS and site creation approaches.
The post author seems to have not reviewed at least the Hugo docs very well. One clean sign is that he listed "Page Bundles", "Leaf Bundles", index.md and _index.md as "different concepts", when in fact they are all Page Bundles.
Also the author completely missed the point that everything is a "page".
I wish I had time to write a detailed reply to this post but looks like the author has made up his mind to puke on Hugo. I hope this reply serves as a warning that the author's warning about Hugo is very uneducated.
AMA regarding clarification about Hugo in that post.
Nothing that you wrote really comes across as anything but 'yeah, Hugo is complicated'. Which is sort of the point of the specific call out of Hugo.
And I've been using it for a very long time now. I actually wrote the original _index.md explainer page for the docs at the time the switch was made to stop it being 'abused' for section front matter. At least, I think that was the work around people were using, I forget after all the changes there have been.
Hugo is a powerful tool. I'm sure there are ways to do almost anything with it, and some of them answer the critiques in the article. But it's constantly changing (it's still a long way from version 1.0) and its power and flexibility bring a steep learning curve and their own way of doing things, which seems to also be what the article is commenting on in general with static site generators.
My point in that article was indeed about complexity and the difficulty of learning many concepts. How do you figure which concepts are actually "the same"? If they are indeed the same, why ask users to pay the cognitive cost of learning five concepts then figure out that they’re synonyms? But are they really the same, though? I gather that they must do a few things differently. In my experience when I renamed a `index.md` to `_index.md`, I lost access to one feature and got access to a new one (my issue was that I actually needed both!).
The section I wrote about Hugo, and indeed my whole article, is not purely about technical capabilities. It’s about user capabilities when using specific software, so there’s some focus on what the software can do, but also on the user’s perception of what the software can do and on the learning curve.
In my day-and-a-half with Hugo, I’ve read most of the docs twice, and have read some old issues and release notes. It looks like some of the complexity in Hugo’s design comes from adding features and redesigning some features over time. This process tends to accumulate cruft, and calls for compromise between conceptual clarity and backwards compatibility.
At one point I’ve read release note (for 0.20 I think) that said something like “from now on, everything is a Page”, but was surprised that different kinds of pages had access to different kind of data, somewhat arbitrarily. By contrast, if you start with a concept like “everything is a page and has a predictable feature set”, it’s easier to have this simpler design correctly implemented and correctly reflected in documentation.
My comment was directed at the incorrect statements that sound like facts that the author made.
I am not saying that people are born knowing how to use Hugo. Hugo is powerful. If you want to tweak it (the theme), change how your site looks and all, you would need to understand how Hugo works, learn templating,etc.
If you are happy with one of the existing templates, you don't need most of that.
Nothing comes for free. You either learn or live with what an existing theme has. I think, this applies, to anything in general.
But now you may be wasting time dicking around with it instead of focusing on the goal of writing content. In my experience the procrastination of DIY is very tempting and it’s fun to pretend like you truly needed to DIY.
Agree entirely that SSGs are completely for developers. I recently wrote on a similar theme, hypothesising a static site generator for "the rest of us": https://1rick.com/static-sites.html I really wish something like that existed.