I almost agree. The thing that keeps me coming back to static site generators is HTML partials. Having a header.html file that defines my navigation, that I can edit once and include everywhere, is why I pay the complexity tax.
And since I'm already there, I do also like scss + file watching / hot reloading. Though would happily live without it, if there was a 'native' solution to e.g.
<html>
<% include './header.html'>
<body>
...
</body>
<% include './footer.html'>
</html>
The only difference between a service side include and a static site generator include is whether the include happens build time or serve time (and cached). Any issues with including will be exactly the same regardless of where this happens.
If you're running your server, though, it's another level of complexity and support compared to uploading your pages to some static CDN or bucket (yes I know a CDN is a server, but it's 1. a solved problem 2. not maintained by you).
I do a ton of devops/infrastructure so I hate to use myself as any sort of benchmark, but is it really that hard to run your own VPS with Nginx? Especially nowadays, there are tons of pre-canned examples you can tweak and AI can write most any nginx.conf you need as well. If you're just serving static content, you can scale to massive heights with Nginx on a small VPS with Cloudflare in front.
It's not hard but why even bother with it at all just to serve static files? If I have Cloudflare in front of the VPS, then I might as well just use Cloudflare Pages where I can git push to deploy, and avoid paying for and administering a VPS.
Nobody writes and maintains fully individual HTML pages, everyone uses partials/templating with server-side code (perl, php, python, ruby, js) since about 1999.
The only difference between SSG and dynamic backends is the point in time that you're generating cacheable static content.
I fool around with it a while back with modern js framesets are actually good. They feel much more like real applications and are much easier to work with than the dynamic js rolercoaster.
Say you have a menu + banner at the top. It's its own document. looking at the source it all makes perfect sense. The css only affects this frame so you can just target the links image or list items directly without a class or id.
Then you click on the links (at the top) and they open different side menus that are also amazingly simple documents.
Clicking on those opens all kinds of things in the main area. PDF images, video, widgets, error pages, EVEN DIFFERENT DOMAINS!
Or [say] music, in a small frame on the side.
The big frameset issue was that the address bar didn't show a useful url and opening a link in a new tab was a problem. These are now easily fixed by pushstate and you can also rebuild the frameset in a new tab if the user tries to open a link in a new tab.
As there is nothing dynamic about the documents they are easily cached. Clicking around feels like an application!
You can also reuse the side menu frame to open diagrams and charts to accompany the text without scrolling up and down like a madman.
On mobile you simply don't load the frame set. The menu is the mobile application.
We also got <details> and <summary> adding even more dept to the menus entirely without js.
Is not there a problem to have a popup menu from the top frame that will cover and overlap the main frame? As far as I know, frames can overlap only their parents - but not their siblings.
I'm not sure what you mean, are you referring to iframes perhaps? I mean framesets.[0]
The top arguments here[1] are:
> 1) Frames prevent users from properly bookmarking pages.
Not true anymore since we have History.pushState() and History.replaceState()
> 2) Frames present challenges for printing web pages.
This is just funny in 2024.
> 3) Users coming from search engines may not have access to navigational elements if they are located in another frame — they are directed to only that frame the search engine found the text in.
The top page is actually so simple that if pages that should be framed are loaded on their own they can can just act like a frameset and load themselves into one of the frames[2] (or redirect to the frame set)
Having base64 images within a document encoded saves so much faff of CDNs, excess latency and bandwidth. Gives greater control and more archivability.
Sure the page file size jumps up but web servers enjoy serving large files. Your not losing anything else, you would still be serving xMB from some image service. Possibly double.
If we can serve 8mb SPA applications, we can serve 8mb Base64 images within html files.
Use a webserver with server side includes (SSI) like nginx or apache and you can <!--# include file="/header.html" --> in the other HTML files themselves and it's all completely transparent. No need to 'build' or anything. And no complex software stack to mantain or worries about attack surfaces like with dynamic languages like php. Just the bare minimum power to do templating that hasn't changed or had issues in 20 years.
Well, except for the webserver with nginx or apache, correctly configured with SSIs enabled. It's not terrible -- but not 'obviously' less complex than using e.g. 11ty (a static site generator) + uploading to an s3 bucket or FTP server. Just trading off complexity in one place for complexity in another.
A sibling (top-level) comment suggest a standard HTML templating (or SSI) language that many static hosts would support. I like that idea quite a bit conceptually, though of course much easier said than done.
But client-side includes are inherently slower on first load than server-side includes, because they require an additional round trip to fetch the partial content.
That performance hit is particularly painful for the header. You either have to show a flash of content without the header, causing the page to jump around when the header loads in, or slow down the entire page while you wait for the second round-trip request.
"But what about subsequent page loads, where the header is in the browser's cache?" That's fine, but the savings are pretty minimal. Headers and footers are typically not a lot of bytes on the wire, so there's not a huge savings.
If all you want is the developer experience of writing HTML "by hand" without copying and pasting your header, server-side includes are a battle-tested solution.
HTML itself doesn't have it because HTML was understood to be an SGML application/vocabulary, and SGML does have mechanisms for fragment inclusion/sharing. For your requirements (pretty much the simplest case), you'd use entities:
<!doctype html [
<!entity hdr system "header.html">
...
]>
&header <!-- content of header.html gets included here -->
... page body content goes here ...
SGML can also take care of inferring omitted <html>, <head>, and <body> tags here.
Moreover, you can also use more sophisticated entity expansion and template mechanisms with type checking, proper HTML-aware auto-escaping (for things such as potentially malicious user-provided comments), table-of-content/nav generation, etc. etc.
Because commercial browser vendors felt that effectively permitting re-usable components without the need of Javascript could normalize the user of No-JS websites which would be bad for ad/tracking purposes. Note that web-components today mandate use of JS. You can't disable JS.
True, though you probably only need to invert some relationships to get the same behavior. Instead of a page including the header it wants, you have it iframe the content you want. Your landing page, then, can use javascript to pull out the location to know which page to include.
Functionally, it would be about the same? Caching would even largely go the way you want it to with it hitting the main layout page first, and then pulling in the content pages.
Edit: Amusingly, this organization strategy also provides a relatively easy way to try out other layouts. Since you can make a new driver page that iframes in your content.
Sure, but the <head> doesn't go into the body DOM either? Pretty sure header.html was supposed to be the navigation/menu and similar, so that wouldn't be in the <head> either
You are missing the point. Repeated document fragments have been a pattern since the very beginning of HTML. This is a missing feature. Hypertext pre-processors are just a workaround.
> . Repeated document fragments have been a pattern since the very beginning of HTML. This is a missing feature.
With webcomponents, it's now trivial to do client-side includes. It's not really a missing feature anymore. See this post here (which, for some reason is being downvoted): https://news.ycombinator.com/item?id=40847759
Sure, but only for implementing your own. In practice they don't typically require the author of the page to know any Javascript. I'm using a client-side include by writing only HTML tags (with a 'remote-src' attribute).
It's no different from not having to know C++ in order to write HTML which is rendered by C++ code. The implementation just doesn't matter, because the user (in this case the page/site author) never needs to examine it.
One thing that seems to get lost in modern programming is the JS frameworks arose in a time where HTML5+/CSS were also growing to gain some of those capabilities.
For example, Web Components, Web Sockets, etc., are all pretty capable assuming it's a feature implemented in the browsers.
In a recent project / prototype, the task was to build video capture and playing from scratch in html/ vanilla javascript. It was surprising how far it got compared to the libraries and frameworks out there.
In the end, there were some tradeoffs to both but the consensus was no one had every considered HTML/JS alone could do it (even though js frameworks use.. js).
Javascript30.com is a handy spot for new to JS developers to learn Javascript how I think it should be learned. First Vanilla, then Libraries, then Frameworks, in that order. Each helps fill in the "why" of the next.
Yeah the object tag is there but what I mean is do any browsers support using it for embedding HTML?
I’ve mainly seen the object tag used ages ago back when people had Flash animations on websites. I remember Java Applets also but I think at the time people were using the applet tag for Java Applets. PDFs might also have been using the object tag however.
I liked CityDesk so much I wrote a clone of it in Xojo (then Realbasic) about 15 years ago. It has wysiwyg, templates, uses sqlite instead of a MS Access DB. Sometimes I think about making it public but don’t know if anyone would be interested these days.
If you want to learn the arcane ways of m4 (probably already available on your system if you're ever had to build from source a project that uses autotools) you can use the include function without rolling your own with a bit of sed or awk.
This is how I got into web development. I was taking a web design class in college (back in 2002 or so). I had built a 20-ish page site for a project and got tired of copying and editing my header and footer. Initially I used frames, but then I discovered php. My professor was pissed at me because, in her mind, this was the art department, not the CS department, and if I wanted to do that stuff I should get out of art. Little did she know that I was getting minors in both while studying 3d animation.
The native client-side solution is called XSLT. You need to invert your flow a little (the header and footer are merged into a single xml file that includes a placeholder for the body) but that's easy enough.
So, there are basically 2 things people use XSLT for. You can use it to extract data, or you can use it for templating. The former is generally trivial (it's generally just a set of hard-coded output nodes + some xpath), so I'll only discuss the latter.
For templating, there's a simple rule: always start with the identity transform:
(In particular note that `xsl:copy` is the only bit here that's largely interchangeable with non-xsl nodes in the stylesheet.)
Then, generally, you'll add `xsl:template`s that `match` some hard-coded node names (or the root) and add some other structure instead of `xsl:copy` before (if not switching to simple extraction) calling xsl:apply-templates at a deeper depth.
In my experience, attributes are likely to only ever be copied all at once or not at all (e.g. if only made available for extraction), whereas nodes are likely subject to more complicated logic.
For the specific case of a header-footer template, you'd match the root and hard-code the structure instead of using xsl-copy, then use apply-templates where you want to insert the main body from the file that's calling the template.
Also, remember you can test with `xsltproc` to avoid browser overhead. `xmllint --xpath` is useful for selectors as well.
This is my favorite concept: writing HTML by hand, but having a static wrapper, which also takes care of links and their validity, and things like tags, public visibility of posts, RSS feeds and so on. (The data feed for this may live in a static data file, as this will be still of moderate size — you probably won't have multiple hundreds of posts — and loads without db latency. As a bonus, since there is no input and no query, this should be quite secure. Or rather, as secure as you basic server setup.)
I'm in the middle of making a small website to document some recent travels and I just ran into this problem. I looked at SSI but as you said elsewhere it needs to be configured and then I lose hot reloading support.
So what SSG are you using? I was going to just make some jinja templates that I re-render with my own script, but it would be great if there was something that supported this out of the box without going crazy far up the complexity ladder.
Not OP, but I really like https://www.getzola.org/ because its a single binary (I switched when I realized I could no longer easily build my Jekyll setup locally), has templates that make sense to me (i.e. similar to Jekyll), and hot reloading.
Depends on your language of choice. Personally I use Eleventy[0]. Written in JavaScript (so you'll need node & npm). Has very minimal default settings but highly configurable. Pick your templates or just use markdown if you really want. Hot reloading is enabled by default.
I'm partial to mkdocs. It's designed for documentation sites, but the mkdocs-material theme provides enough functionality to make it well-suited for blogs and adaptable for almost anything.
I entirely agree with the sentiment "writing HTML once is easier than using a static site generator". Hell, even writing it twice is probably easier. The point of a static site generator is there is lots of HTML (like headers and menus) you don't write just once or twice, or if it is generated from data in a database you write at all.
I'm sure the author of the original post would agree in general, so I was left scratching my head what he is actually objecting to. Going by his comment "This becomes obvious when you eg get a new work machine and need to set up the site generator on the new machine and realize that the exact series of bits you had on disk on the old machine were different than what you can achieve on the new machine" maybe it was a rant about how complex tool chains have become.
Or maybe he's just now coming to understand why people stick to what's in Debian Stable, forgoing all the new shinies NPM and the rest of the ecosystem offers. It doesn't take too many replacement laptops before than realisation dawns.
I did (still do) this for years but it just feels... wrong. I recently hand built a personal site and used JavaScript to insert the html header/footer. Not great, but it worked.
For me the issue is that Jekyll is pretty terrible, and I guess something is iffy with ruby somehow? I don't really know or want to find out, I just want to publish my little blog.
Yea, me too. If I follow the advice of GitHubs dependabot screaming about exploits in the markdown renderer, then it breaks 100%. I just had to silence it.
That's actually pretty easy too. Take a look at an RSS file. There's a reason it's called really simple syndication. Adding another entry to an RSS file with your text editor is dead simple.
Added friction means less writing, in my experience. But that depends in his often you update your site, I guess. I'm bound to believe that more friction means less updates.
I suppose if I were posting 5 times a day rather than 5 times a month doing the below would get tedious,
<item>
<title>It's not that hard</title>
<link>http://www.superkuh.com/this-link-doesnt-exist</link>
<description>This is an example of how quickly I can add a new item to my RSS feed.</description>
</item>
Or if you wanted to syndicate via RSS rather than just linking, which frankly reads more like an SEO move than one intended for the benefit of human eyeballs...
After many years of using Hugo as a static site generator and moving my blog from blogging software to blogging software over the years I realized:
- It's fun to play around with static site generators as a technical person
- It's very annoying to actually write content (As you link images by using the file name, no nice editing interface, using a markdown editor is clunky as features of the blogging software (Embedded videos tags etc.) are not supported
- It's impossible for non-technical people to use it. My main reason why I would never introduce a static site generator for documentation at work again.
- You still need some kind of tooling to generate RSS feeds, sitemaps, pagination, so I've settled on https://getkirby.com for now which has a nice editor interface but is file based and doesn't need a database. Makes it easy to backup and move between hosts if needed.
Static site generators are so simple and powerful it blows my mind that anyone would suggest plain html is a suitable replacement unless your site is like 5 pages. They're so simple to build too, so if you're miffed about bloat you could throw together a simple md -> html system in a few hours, if not minutes.
Plain HTML is pretty simple and powerful too. I don't really have a dog in the fight because I don't have a website, but I don't think it's unreasonable that some might find it easier to just write HTML by hand.
IMO the main point of an SSG isn't that you can write in Markdown, it's stuff like templates and includes for headers/footers, automatic generation of RSS, site directories, tag clouds, etc. You still need that stuff whether you write HTML or MD.
Static site generators vary greatly in complexity. I typically use a Makefile or Bash script that calls Pandoc for all the markdown pages. Also, writing html by hand is not really necessary in any circumstance. You can write the markdown directly in the html files, use a CDN for markdown conversion, and you're done.
The author is referring to a particular generator, which I agree can be a ridiculous process.
Really, my art site has 1600 detail pages, and I wrote my own site generator (in Swift) for it. You think I would want to write all of them by hand?
Sure, I could have a dynamic site (ROR, or Express or whatever) but static is easier to serve, and changes are quickly diffed except once a month when the structure is updated.
If was just doing a small site, sure, but anything substantial requires something better.
Static site generators are very simple... so not really understanding what they are getting at. And for all the people who seem to struggle with writing markdown files or using a static site generator check out pagescms: https://pagescms.org/
Yeah, they're actually simple enough that they're kind of a perfect way to learn a new language... You get to try something that is pretty familiar (transforming some source files into some destination files), small enough that you can actually build the thing in a weekend, and big enough that it isn't just a toy program--it will give you a tour through the standard library, the build tooling, the package management / ecosystem, etc.
You can also use it to play around with different programming paradigms--I recently rewrote mine from Rust to Go and played around with a maximally parallel architecture (what I thought would be a fun throw-away experiment quickly became my production SSG): https://blog.weberc2.com/posts/efficient-ssg-with-csp.html
Generally speaking, all I really want from an SSG is to be able to keep my pages in a format that's more readable than raw HTML. A few years ago, that was reStructured Text. Since then, it's been Markdown. Shortly after CommonMark came out I converted all of my ReST docs to it, and haven't looked back.
Theming, shared blocks, etc. are all handled just fine by using includes. If those are stored in Jinja2 templates or HTML files that use SSIs is pretty irrelevant to me.
> "Do you enjoy debugging programming language installations? What about the language’s package ecosystem? What about the language’s deployment model (or lack thereof)?"
Switching to a generator that ships as a single binary largely resolved this for me.
With https://www.getzola.org and similar you only need worry about installing the same version as the one that's building your site in production.
For simple static sites with repetitive sections I don't want to write by hand, I find that building a simple generator in Ruby with ERB templates that loop over the rows in a SQLite table is the simplest way to do this. There's no dependencies to pull in, the ERB templates are already pretty close to HTML already, and there are plenty of GUI tools for SQLite files that make it easy to add rows by hand.
This is extremely underrated! ERB is a phenomenal tool for static site generation. Great templating language, excellent CLI tools, easy to wrap a script around. I honestly wish I'd done it sooner.
I'm surprised no one mentioned Dreamweaver here. It's technically a "static site generator" as well but without any of the problems that the author is talking about. You make templates, you make pages that substitute things into the templates, you generate a bunch of html pages, done. All with a nice GUI, live preview and optional wysiwyg.
I bit my html teeth on dreamweaver back when it was a macromedia piece of software. I thought today it was abandonware.
My problem back then was it was hard to understand what features were server side and required a special host (e.g., your all important visitor counter) what was generated by dreamweaver and what was handled client side.
I’ve been seeing a lot of these kinds of posts and sentiments lately.
Yes, it _is_ easier to write plain ol HTML. But how do you handle consistency by hand writing each page? How do you scale your site or add * number of posts or headers and footers that do things like show the latest post? If you update a link somewhere, how do you ensure all the links pointing to it are valid?
We don’t do these things because we’re masochistic. We do them because they, on the net, make things easier. I suspect this sentiment is some kind of new version of the Eternal September, where people previously unexposed to the hardships of creating functional websites think we somehow missed something in our slow march toward where we are now.
I happen to have a hand built static site. It had two pages. When I built the second page, I took the first html file, copy pasted it into a new path and made the changes. That works splendidly for a two page site. But most sites are not this way, I imagine.
> How do you scale your site or add * number of posts or headers and footers that do things like show the latest post?
It depends on your needs, some use a templating language (like Handlebars, Nunjucks, Pug, etc), others might write a script to build the site
The problem with many static site generators is that they grow beyond their initial mission and get bloated in an effort to please a wider audience, so previous adopters get tired of the imposed complexity and problematic dependencies they didn't need or ask for and start looking for simpler solutions that meet their needs.
I want to migrate, but my blog currently has this cool thing and I need it.
And since the audience probably can't settle, and keep trying different setups, all SSGs grow in complexity and more or less reach feature parity among each other.
> That sounds an awful lot like a static site generator to me?
Right? They didn't abandon the concept, they just picked a solution that better fits their needs. Less headache, less abstraction, and less surprises overall.
As the maintainer of the Python-based Pelican static site generator for over a decade, I can say with confidence that my experience has been nothing like what is described in this article.
Most of Pelican’s code was written by other people, and yet I have spent almost zero time debugging that code, much less my own. After taking advantage of Pelican’s rich plugin ecosystem and adding a handful of useful plugins, I continue to be amazed by how much time this publishing system saves me, and how little time I must spend to keep everything running smoothly.
What it would take to accomplish this by writing HTML by hand instead… I simply can’t fathom it. But once again, that’s just one person’s experience, and YMMV.
If you're an Elixir person, the last year or two has had some interesting developments. For example Vox[1]. There's also a nice roll-your-own SSG using Phoenix[2]. I don't know why Elixir-based SSGs seem to die out quickly, but hopefully something will stick!
The beauty with a static site is that if you have a copy of the generated output, using the site generator becomes optional. You can always move away from using it (but not moving back).
This means that a "custom buggy sitegenerator" is never a bad dependency to have.
> This becomes obvious when you eg get a new work machine and need to set up the site generator on the new machine and realize that the exact series of bits you had on disk on the old machine were different than what you can achieve on the new machine. And as a result the site generator doesn’t work even though the setup is “the same”
That's why I never use ANY tools like this without getting them working in something like GitHub Actions (which is effectively free these days, and all the good LLMs know how to write YAML workflow files for it.)
If you outsource the running of these tools to a CI service you don't have to worry about setting them up on new machines.
I've pretty much committed to GitHub Actions at this point, under the hood it's just running shell scripts on a Linux machine so it's a pretty solid base for deploying to whatever hosting I might use in the future.
I'm happy to hand author a small site, but the line for me has been around 3 or 4 pages before I reach for one templating engine or another.
For something like a marketing site, the homepage is usually custom enough that you wouldn't repeat yourself much. Throw in an about us or contact page and you'll be fine. Much past that and I want partials for basics like the header and footer, and likely a few layout components.
Debugging a static site generator should be a thing in my opinion. When you gave to debug an SSG it's because the tool has to much magic built into it like automatic data pipelines, opinionated front-matter schemas, etc.
If there was a code editor that _actually_ supported the HTML language as it's specified, and allowed you to select by element in the editor as well - that would be amazing.
Right now the problem I have is that text that's been marked up as HTML suddenly then becomes harder to wrangle around than it was to put it into HTML in the first place.
I want an editor where I can "select all <p>" or "search and replace all <h2> tag names with <h1> tag names while leaving attributes intact" and other ways of reasoning about HTML as HTML in my editor.
Writing my own SSG was the best investment I ever made into my own sanity.
The only drawback is that I can't really help people when they ask me for an SSG recommendation since most people won't want to do the same. I recently suggested to someone that they use Jekyll (after I did a small amount of research) but reading these comments makes me worried that was a mistake lol
So this good advice until you need templates, which you need if you want for example syntax highlighting (include the css and the js file which parses code). From there, it's all a nightmare of having to re-sync every template change and it becomes not worth it.
Another option is having the site generator packaged as a docker image and executed via a CI pipeline when the static files are pushed to a git server. Relying on stuff installed on a local laptop for the publishing pipeline isn't sustainable.
For a static site I'll use Django and its admin site as a CMS because that's what I know inside out, then I'll use wget in its spider mode to get a static version of the whole site. Has worked great for simple enough sites.
If we’re talking Jekyll, I completely agree with this post. But Hugo is a single binary that runs on practically anything. And it does stuff that would be a huge pain otherwise, like generating responsive image sets.
this is one of those things that's true for the trivial case, and then quickly falls apart as soon as you add even the slightest amount of complication.
writing html by hand is easier if you post infrequently, you only post basic text content and you're the only contributor. if you're posting daily, or you're sharing photo galleries, or you're trying to manage contributions from multiple authors, or you have any styling more than the absolute most basic stylesheet, then you're going to last about a day before you start trying to automate things again.
DevContainers have solved this problem for me.
If I want to update my site from a different machine, I just need to git clone and open the folder in vscode.
I mean... I used to do that back in 1997. Before I wrote a perl script that would generate my site from a bunch of text files. My script would also ftp the files but that was replaced by rcp.
The benefit was making sure the links all worked and common page elements like the site navigation, header, and footer were all consistent.
Many folks in that era would use an IDE like HomeSite, FrontPage, and DreamWeaver... these would have template features that you would generate your site from. These tools were very much like using my script only slow and expensive.
I do get where the author is coming from though. There are some static site generators that pack more features and require more configuration than a space command centre. I don't get the appeal of those. The key is to keep it as simple as possible.
I have to agree. we have way too many layers of abstraction in front end development these days. you may be able to generate a static site quickly but good luck coming back to it after 10 years.
how many of the dependencies will still be maintained? will it still even build?
back in the day tools like jQuery were a godsend for ironing out the browser incompatibility but now standards are much better.
well supported tools like that were a great abstraction point to help simplify the codebase and provide consistent functionality in an ever changing landscape of web standards and browser compatibility.
today we have the opposite problem. we have a incomprehensible mess of middleware designed to help out in some way or another but when you add it all together you end up with a 10MB hello world with 3,000 npm dependencies.
recently I decided to write a PWA using only hand rolled HTML and JavaScript and it was a pleasure. the only dependency I had to add was Nosleep.js for safari. it was extremely satisfying compared to dealing with a more modern toolchain.
I've had some Jekyll and Middleman sites around for ten or more years and it's fine. Now and then something breaks and needs fixing. The Ruby 2 to 3 transition involved breakage, but nothing too bad.
Certainly beats having to change the header or the footer in a thousand pages, or headers getting out of sync!
> you may be able to generate a static site quickly but good luck coming back to it after 10 years.
If you're using Jekyll or Hugo or similar, sure.
My SSG is a tiny shell script that calls pandoc. I have no problem coming back to it to fix it, but because it's so small there's literally nothing to fix.
And since I'm already there, I do also like scss + file watching / hot reloading. Though would happily live without it, if there was a 'native' solution to e.g.