1. 11
  1.  

  2. 4

    I build static site generators for almost every project I have that needs a site (my personal blog build script for example), except for the ones that only have a single page (like dbcore.org. Each time it’s ~200 lines of code that lasts me years with only minor tweaks. I much prefer that than having to deal with breaking changes by 3rd party generators over the years.

    My basic formula is file system walker + markdown parser (when I’m not feeling lazy) + jinja or equivalent template engine for layouts. Actually my personal blog doesn’t even use jinja it just uses Python string templates which has… worked ok for years. Eventually I add crazy things like RSS feed generators and I’ve been thinking about adding a static site search where indexes are built from posts during deployment and you just use JavaScript to search indexes in the browser. Having a link checker and spell check pass might also be nice.

    And after reading all that you might say it’s a waste of time to build your own and on bigger projects I’d probably agree with you. But again the benefit is that you can start very quickly, small, and only worry about breaking changes in the generator when you want to.

    1. 3

      If you’re worried about breaking changes isn’t the solution to just not upgrade?

      1. 1

        But then you’re stuck on an unsupported version. So you’ve now taken responsibility for their whole ecosystem.

        1. 2

          I don’t see how being on an unsupported version matters if it works for you and you don’t want it to change? Just how your self-built one works for you and isn’t a pain because you basically never change it.

          1. 1

            As soon as you do want to make your own changes then you have to deal with the breaking changes too.

            When you build it yourself the only changes are ones you want to make.

            1. 2

              If I use, say, Jekyll or Hugo, then I can use a specific version of it. I’m running it offline, on trusted data, so I don’t care about security vulnerabilities. If there are bugs, I can either fix them or work around them. If I upgrade then there may be some breaking changes and I can decide whether the new features that I get for free are worth the pain and I can benefit from an ecosystem full of useful things like BibTeX-compatible bibliography engines, FreeBSD man page links, and other fun stuff.

              If I write my own SSG, then I can use a specific version of it - the one that I wrote. I’m running it offline, on trusted data, so I don’t care about security vulnerabilities. If there are bugs, I can either fix them or work around them. I can’t upgrade except by writing more code and I don’t benefit from any other contributions or from a wider ecosystem. Every feature that I want, I must implement myself.

              It’s really hard for me to see how the second option is better than the first.

              1. 2

                Before I write more I’ll clarify I’m really not trying to convince anyone per se. :) Just sharing my experience.

                Maybe a differentiating factor for you and I: do you generally find it easier to contribute to projects you don’t own (and are driven by a community of many people) or projects that you were the solo dev on?

                For me it’s always easier to contribute to my own projects than to get into existing ones. I’m not saying one mine is better in any way just that mine are smaller and I already know them.

                Maybe the point that’s closest to me trying to make an objective argument is code size. How many lines of code is Hugo or Jekyll, including dependencies? Those are lines of code you’re on the hook for.

                1. 1

                  Maybe a differentiating factor for you and I: do you generally find it easier to contribute to projects you don’t own (and are driven by a community of many people) or projects that you were the solo dev on?

                  It can go either way. For project with a good test suite and CI infrastructure already, it’s easier for me to contribute than to a project that I set up myself and haven’t set up the relevant infrastructure yet, as long as upstream is receptive.

                  There’s also a difference between three categories of change:

                  • Changes that I upstream, which must be useful to others and production quality.
                  • Changes that I carry locally (or in a downstream form), which can be small tweaks that break it for others but improve it for me.
                  • Changes that are layered on top of something else.

                  With Jekyll, there’s a lot of scripting available in Liquid and there’s a plug-in interface, so I can maintain downstream plugins if I need to but everything I’ve actually needed was either already implemented by someone else in a plugin or possible for me to implement with Liquid and carry in my site’s repo.

                  Maybe the point that’s closest to me trying to make an objective argument is code size. How many lines of code is Hugo or Jekyll, including dependencies? Those are lines of code you’re on the hook for.

                  That cuts both ways. A lot of the code in Jekyll does stuff that I want. The lack of it in a from-scratch implementation is code that I have to write. I don’t have to maintain them in the upstream repo, I only need to worry about when they change things in ways that affect my own site. This happens, but it has generally meant that I need to spend a few minutes tweaking a couple of lines of Liquid for a major version bump. That’s orders of magnitude less effort for me than to implement something like Jekyll-Scholar from scratch. And if I did, I’d probably end up using some of the same libraries, so I’d be just as vulnerable to API changes (if not more so, since Jekyll-Scholar provides interfaces designed for end users, whereas libraries provide interfaces intended for developers).

    2. 2

      I did this (gensite) for my site as well. Producing good HTML5 with all the expected bells and whistles is just too hard to do by hand now, to the extent that it is actually easier to throw together a few hundred lines of Python (in my case) than to edit the site directly.

      I did search for existing static site generators before embarking on creating one but couldn’t find exactly what I was looking for. With the right libraries, creating a static site generator is actually easier than learning to use an existing one.