A while ago I decided I was tired of handcrafting an individual .php file every time I added an article to this website. So I decided to shop around again for a static site generator. I had used Jekyll a few years ago so I thought I'd give it another try. This time it was broken on arrival–I forget how–so I swept up all the little rubies and gems in my home folder and went on with my search.
Hugo was still as sparse as ever, so after a bit of looking I settled on Pelican, and found a beautiful theme called backdrop at backdrop pelican theme, which I modified using his updated css from his personal site, my colors, etc.
Things went well until one day last December I started editing a new article and got an error message. "Oh no! Why me? Why now?" I was using Debian Sid, so my second or third thought was "I wonder if there was a major upgrade? Let me go check." Sure enough, pelican 4.0 had been released November 13, 2018, and had just hit Debian's unstable repository without my noticing.
The logical place to look for help seemed to be the theme repository on github. In fact, Googling one of the error messages turned it up as a top hit. But the theme doesn't seem to be currently maintained, as the writer has gone on to bigger and better things. I mean that sincerely, without saying more about him than is required for this context. By the way, are any of the pelican themes maintained?
It looked like I was on my own. Welcome to the world of code hacking. Well not quite, I'd adjusted a few files in Gramps, article to follow someday. But this was more serious. Without a working site generator I'd be going back to writing each file by hand.
The first error message had something to do with slugs. Besides being slimy creatures that get run over by cars, slugs have something to do with naming your files, don't ask me what. I found the 4.0 docs, even though Google still insists on listing 3.x higher, and fixed the slug format. Not too hard.
Next was a message to the effect that PAGINATED_DIRECT_TEMPLATES are removed in favor of PAGINATED_TEMPLATES. OK, I'll just change the name of the setting in pelicanconf.py. Nice try. Pelican said "not so fast" and gave me the message "articles_paginator not defined."
Real code problems
Big trouble now, since that looks like some deep code thing, either a variable, object, inductor, conductor, or some other abstract noun way beyond my expertise.
I turned on debug mode, and was either further confused or able to trace the error to a specific file in the theme. Probably the first, since I think I found the file by just searching for "articles_paginator" in the theme folder. I couldn't for the life of me figure out what it was doing and how to get it to stop. Or, in programmer speak, what values it took and how to feed them to it.
A tactical retreat
I gave up, downloaded pelican 3.7 from the Debian Stretch repository, put a hold on pelican in the package manager, and went back to the .php format anyway. But that gets tired quick. If you want to delete a file, you have to delete all references to it in your tags, categories, and archives files as well.
'It was pagination, my love'
So last weekend I worked up the nerve to take another run at pelican 4.0. I looked again at the error messages and realized that the ones that were causing the trouble all had to do with pagination. Now I didn't use, need, or want pagination. Could I take it out of the theme on my own and make things work? Not a chance.
So I went through the pelican themes on github and found someone who felt the same way toward paginating as I did, namely "We don't do pages." I grabbed the category.html file from the Just-Read theme and dropped it into my theme folder. It worked! I modified it for the tags and archives pages and they worked too!
I didn't like everything about it though, so I cut out the unordered lists and the date stamp. And I really liked having a summary of each article on the category and tag pages. So I grafted back the code from the backdrop theme for summaries, and Voila! things were just the way I wanted them. The results are what you see on the main part of this website. If you like the theme, you are welcome to it. You will find it in https://branchriverjournal.com/theme/. The background picture is mine though—I'd prefer you didn't use that, at least not without asking.
So I changed a few configurations, removed a couple of settings, and swapped out some code for some other code. Do I understand eveything I did? Not really. Do I know how it works? No, but I know it works. Do I have to understand it to use it? I hope not. Besides, how many Python programmers know what Griffith's Valuation is? Hint: it's not an algorithm.
The drawing of the blank pages came from pixabay.