Stuck with a series of static site generators

[lovingboth]

There's a non-bi community website that I'm responsible for.

For most of its life, it was using WordPress. When its server was changed last year, I took the opportunity to change it to a 'static site generator' - it wasn't updated very often, doesn't want anyone's comments, and serving plain HTML files is much quicker and vastly more secure than something looking at a database to go 'Oooh, what's on this page?' each time.

It's obviously possible to generate the HTML in a plain text editor but it's not 1994 any more and it's very useful to be able to say 'here's the content specific to this page, the rest is as usual / like this / etc'. And that's what an SSG does for you: feed it some text in some simple format and it will gather everything together to make your webpage. Want to change the colour of the menu? Want to change the entire theme? It's likely to be changing a single line in a single file and, on running the SSG again, every page will pick that up.

I can't remember why I picked Pelican, but it was possible to get it to work without too much problem and that's what the current version of the site was generated by. The 'simple format' is Markdown - very easy to use, to the point that I use it on DW - and the program that does the work is written in Python.

One problem is that the number of Pelican themes is low and they all look rather 'meh'. Various people would like it to look nicer, including me. The other problem is that Python can be a pain in terms of keeping the various versions of various libraries in sync and not interfering with other Python programs' versions. You can do it (and I did) but that work would need doing again because of an operating system change.

OK, Hugo is popular. Again, it will take Markdown input, but this time the program is a single file, not dependency hell, because it's a compiled Go language program rather than a bunch of scripts that need to be loaded and kept apart from each other and... As a side effect, it's also quicker (not that it matters in this case: sixty pages being sorted in a fraction of a second rather than a couple of seconds..) There are some very nice looking themes for it too.

But my ghod it's not newbie friendly. There is far too much you're expected to just know. One example is that it doesn't come with any theme at all and until you've installed a theme it won't work. Other systems will show you something, even if it's only HTML formatted text in your browser's default typeface and colour etc. Not Hugo!

Real Hugo Users are clearly expected to just write their own theme: the first thing the documentation wants to tell you is how its templating system, the bit that makes up most of the theme, works. But installing themes is sometimes (relatively) simple - "Clone the Ananke theme into the themes directory, adding it to your project as a Git submodule" - and sometimes needs you to know what dependencies need adding and where. Sometimes you need a different edition of the Hugo program itself. They made running the program simpler but using it harder!

OK, I can manage to get a theme that people like to work and I can change things like its default menu to be what we like. I don't know why it insists on adding a bunch of images etc from its sample site from somewhere that's not in the place where you go 'Hey, Hugo, turn these into a site for me' but I can probably delete them every time. Probably.

If you've ever used a content management system like WordPress, you may remember that there are two sorts of bits of content: posts and pages. Posts are like the entries here in that they have a date, an author, and are typically shown in batches of five or ten or whatever together. When a new post is created, the oldest (typically) post will drop off that bit of the website and go onto another bit, probably pushing something off that one etc. Often, just bits of each post is shown on that place on the website and to read the whole thing, you have to look at them individually.

Pages don't have dates and probably don't have their authors shown to visitors either. The often make up the bits of the website you get to from navigating a menu rather than clicking on a 'show me the next ten posts' link.

All but possibly one bit of this website are pages.

In theory, what Hugo does is look at everything in that 'turn these into a site' place on your computer, and for the bits you've said are pages, turns them all into webpages with a URL you can control.

It does this for a handful of pages but not the rest. They're just ignored. I have no idea why. If I make minor tweaks, some new pages work but almost invariably some that used to work stop being converted. As I say, I have no idea why. It also almost invariably doesn't put it in the bit of the results that I have asked for, in the way I have asked for. Again, no idea why.

Quite possibly, I should be using page bundles. These are relatively new to Hugo and hence aren't mentioned at all by most of the guides to using it elsewhere on the web. The main Hugo site's documentation is the least beginner friendly I have seen in a long time yet, from looking at their forum, if you don't understand it, you need to be told you're an idiot for not doing so. (They don't usually use that word, but that's what they mean.)

Even with all that, if the sodding files were all converted into HTML, I'd be happy with Hugo.

OK, Jekyll is somewhere between the two. It has some themes that are nicer than anything Pelican has. It's written in Ruby, another language that wants you to find and install a bunch of smaller bits of Ruby to do anything useful.. but it does make that a bit easier.

But again, some of those nicer themes have an awful habit of expecting you to Just Know what smaller bits they need to work. And while it will import your text from a variety of other systems, neither Pelican or Hugo are in the list. WordPress is and I think I have a copy of the old version of the site's database, I did do a small bunch of edits on the text of many of the pages when doing the Pelican version.

It looks to me that most people use Jekyll as blogs - their tutorials are very 'all about posts' - and not for sites that are a bunch of pages. And, again, not all pages are being picked up by Jekyll and I have no idea why not.

Sigh.

All this is partly as a prelude to converting a bunch of other sites away from WordPress. At the moment, I am getting the feeling that it would easier to do what I did the series of old BiCon sites and use a WordPress plugin to generate static versions. It does make changing things harder: I'd have to tell the web server to stop showing the static version and show the 'real WordPress' one, hope that there was no-one looking to exploit the security holes in the 'obviously hasn't been updated in several years because it's not been online' old version of WordPress before I could update it (and hope that it stayed looking the same, not something you can rely on!) make the changes, generate a new static version, and switch the web server back to showing that.

Sigh.

Comments

[lovingboth]

Ahhh, it looks like Hugo tries to be clever and only converts files it thinks have been referenced by files it knows are part of the site. So files linked to from the front page are included, then files they link to, etc.

Is this mentioned anywhere obvious I can see? Ha.