Lessons from Building a Static Site Generator (2020) (opens in new tab)

This is a good review of a fairly complex piece of software. But don't let this convince you that all static site generators must be complex.

Out of laziness, most sites I run have their own 100-200 line Python static site generator that takes Markdown (if I'm really feeling it) or HTML files with Jinja templates and generates pages around them. The core generator code hardly ever changes year by year. Here's an example [0].

This isn't to say that everyone should always write their own. I am just a bit surprised by all the debate around each generator because they all produce the same thing and the only (or major) variables are the template language and what themes are built in (though of course you can always bring your own CSS).

But _using_ a static site generator is a very good idea. If you have no other inclinations, I think the stack that makes sense for anyone with multiple contributors is to use WordPress for editing and then have a plugin that will generate static pages from it so not every request to your site hits the database.

[0] https://github.com/eatonphil/notes.eatonphil.com/blob/master...

This is a great post, but why doesn't it have a date?

It's infuriating to see blog posts or even news that don't clearly display the publish date near the title.

Alright, I'm skimming this whole idea of newfangled "static site generators" that involve a lot of Javascript and I'm left with a whole lot of "Isn't this just ____ with extra steps?"

I'm seeing "shortcodes" and I'm like -- as in variables and/or configuration files?

Or, more broadly -- why Javascript for the backend? This looks like a silly level of complexity. I'd start thinking about it in Bash and then probably head over to e.g. Python once databases et al start getting involved. What am I missing here?

I went down this rabbit hole and found everything to be overcomplicated for my use case. I'm so sick of static site generators that have seven layers of templating engines and complicated build systems.

Most of the static site builders I tried were either way too complex, or else just straight-up didn't work at all (looking at you, coleslaw).

I tried to go full emacs and use org export (org being my favorite text format) but the default export is horrendous and the documentation for org to html export is so bad it might as well not exist.

Software is simultaneously awesome and infuriating.

So after three days I just gave up on org-export and now I have pandoc shit out an html snippet that I concatenate with a hand-rolled html preamble and postamble via a Makefile.

Found a few rough edges, probably because org is underspecified. It's not elegant but it works for my use case.

What is hydration? You talk a lot about it, but I've never had to add water to my websites before.

I wrote a static site generator for my own personal site. I've been using it for over 10 years, and it's gone through several major refactors / redesigns. A few comments:

1. Template system

There are tons of different template systems out there for things like the "shortcodes" in the article.

    {{youtube id="123asdf4" /}}

My conclusion is that the correct way to do this is with custom tags,

    <embed-youtube id="123asdf4"></embed-youtube>

I apologize for the verbosity... but this is completely valid HTML5, and you do not need anything but an ordinary HTML5 parser to parse this. This maximizes your choices for the libraries you use in the static site generator and it maximizes the level of support in whatever editor you choose to author the site in. For example, you can just use the HTML mode in Vim or Emacs, or you can use VS Code, TextMate, Sublime Text, etc. and get a ton of features: syntax highlighting, indenting, etc.

While on the surface it looks verbose because of the closing tag, in most editors, you only have to press a key or two to close the tag. HTML5, strictly speaking, does not support self-closing tag syntax for custom tags. That syntax is only supported for void elements. There are only 16 void elements in HTML5.

I use "prefix-suffix" syntax to avoid ambiguity... any tag with a hyphen is obviously a custom tag.

2. Routing

Something you can use to tackle the routing complexity is to place your source files in the same path as the canonical URL. You only need routes for generated content, like index pages and such.

3. Index data

You'll naturally want to generate indexes and create previews for links. I suggest that you start by looking at the schema.org schema for web pages and work with a useful subset of that. This way, you can generate indexes on your web page using the same exact data, same exact schema, that you use for the JSON-LD data you provide for search engines like Google.

This is a minor point, but it reduces duplicated effort between the code for generating content for your website and the code for generating JSON-LD metadata.

Don't dive too deep into the schema.org schema, just take a couple bits and pieces that you need, and refer to the feature guides in Google's documentation:

https://developers.google.com/search/docs/guides/intro-struc...

Hey all -- Author here. This was a reflection on building Elder.js.[0]

Happy to answer any questions. I'll be going through and adding context to the questions I see.

[0]: https://elderguide.com/tech/elderjs/

If you are going static with a SSG I think you should embrace HTML5 semantic elements. Write your web site like it's 1999! Only there are much more elements to choose from now with HTML5! Ohh and we have CSS! Don't complicate things! The only real problem is how you get the marketing team to write HTML and use a version control system (git, mercurial, et.al). Or do you give up and give them a WYSIWYG content editor? The thing with semantic HTML is that it's much nicer then a pile of of divs with classes sprinkled over it.

A big thank you to the author for open sourcing this - I've been playing with this to implement a largish static site (11,000 pages) and (as a definite non expert) have found it relatively easy to understand and use - and it's lightning fast.

Just one comment: found implementing a Svelte Leaflet Map component a bit of a struggle - an addition to the docs on this would be very useful.

I'm a huge fan of Hugo because it is a single binary and full of useful features, however I certainly think there is a lot of room for improvement. While Go templating may not be everyone's cup of tea, it is simple enough and the additional functions added by Hugo cover a lot of use cases.

Hugo has shown me that my ideal generator will likely be built with Go, although I could see a C, C++, or possibly Rust equivalent being fine for my needs. However, what I desire more than anything is to have a really performant default template using pagination and hierarchy based on the file system.

I don't want to have to define titles or empty _index.md files to define sections, just want to point it at a nestable directory on my file system and use filenames for pages and directories for sections. This significantly improves the usefulness for anyone, because at that point it can be used as a knowledgebase/note-taking system from the get-go without needing any custom templating to make it work out of the box.

The other important factor is building in search capabilities. While I think that client-side JavaScript and a JSON output works for this goal and can be optimized, Xapian would be a great alternative and extend the usefulness outside of the JavaScript browserbase. So far Hugo has left serving production sites up to third-party web servers, but I see no reason why they couldn't finish implementing the `serve` components to be production-ready and implement a search component and possibly other dynamic components.

I really hope to see someone with a strong understanding of efficiency come in and own this arena building off Hugo's single binary approach, but with an open mind to make it robust to handle all kinds of self-hosted content. Even implementing a bookmark manager using this approach would be awesome, having it auto-sort YAML/TOML/HCL or whatever and be able to serve up searchable bookmarks without even relying on JavaScript. The possibilities are endless with the types of apps that can be built with this design using readable files as data for the content.

I will still encounter many of the issues that they also mentions.

In my experience, writing a static site generator is very much a continuous trade between flexibility and ease of use.

I also agree with most comments that it is often easier to write your own static site generator rather than finding the one to use amongst all the available choices.

That is why I made my own, and obviously I ended up writing a whole bunch of documentation because you can't escape the need to clarify how things work.

If you're interested you can check it out at https://yassb-foss.github.io/

Having recently done a small Gatsby site I can identify with the comments about complexity over time. And graphql does seem like utter overkill too!